> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joyride.exchange/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Current authentication model for HTTP, WebSocket, and admin endpoints.

## Current model

Joyride identifies trading accounts by wallet address.

### HTTP

Authenticated HTTP reads (the query API) require a JWT obtained via SIWS (see the WebSocket section below for the sign-in flow). Send it as a Bearer token:

```bash theme={null}
curl -H 'Authorization: Bearer <jwt>' \
  https://joyride.exchange/api/query/balances
```

For CLI users, `joyride login` performs the SIWS flow and stores the JWT at `~/.joyride/session.json`. Subsequent CLI commands (and the MCP server) send it automatically. The server sets the session lifetime (the JWT's `exp` claim), not a fixed client default; `joyride auth status` shows the exact expiry, and `joyride logout` clears the stored token on shared machines.

### WebSocket

SIWS runs over the **core trading WebSocket** (`wss://joyride.exchange/api/client`). The server requires a challenge/response before any `private/*` method:

1. Request a nonce:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "public/get_nonce",
  "params": {
    "wallet": "GmQozSzrtMjXt5F1Bed8Vrt55zCbiga8vDZr47RX9wC8"
  }
}
```

2. Sign the message `Sign in to Joyride\n\nWallet: {wallet}\nNonce: {nonce}` with the wallet's ed25519 key.
3. Submit the signed payload:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "public/auth",
  "params": {
    "wallet": "GmQozSzrtMjXt5F1Bed8Vrt55zCbiga8vDZr47RX9wC8",
    "signature": "<base58-signature>",
    "message": "Sign in to Joyride\n\nWallet: GmQozSzrtMjXt5F1Bed8Vrt55zCbiga8vDZr47RX9wC8\nNonce: <nonce>"
  }
}
```

Successful auth returns `{ wallet, account_id, roles, session_token }`. The `session_token` is the JWT you reuse as an HTTP Bearer credential (query API) and to resume the session without re-signing.

Accounts are **not** auto-provisioned. A wallet with no Joyride account yields no usable `account_id`; the SDK raises `AccountNotProvisioned` and the CLI prints a "sign up at joyride.exchange" pointer. Create the account in the web app (referral code + terms attestation) first.

#### Resuming a session

Once you hold a valid `session_token`, resume without re-signing on the next connection:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "public/session_resume",
  "params": { "session_token": "<jwt>" }
}
```

### Admin endpoints

Admin routes require:

```text theme={null}
Authorization: Bearer <ADMIN_TOKEN>
```

`ADMIN_TOKEN` is read from the server environment.

For hosted environments, use an issued admin token and send it as a bearer token on each admin request.