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

# Account session

> Authenticate frontend requests using short-lived session tokens

Session tokens are best for frontend applications where you need to authenticate users in the browser. Sessions are created by your backend using the [project API key](/docs/guides/authentication/project-api-key), then passed to the client.

Sessions expire after a period of inactivity but can be refreshed.

## Header

| Name            | Type   | Required | Description                                   |
| --------------- | ------ | -------- | --------------------------------------------- |
| `Authorization` | string | Yes      | Bearer token format: `Bearer <session_token>` |

## Flow

<Steps>
  <Step title="Backend creates a session">
    Your server calls the session endpoint using the project API key.
  </Step>

  <Step title="Pass token to client">
    Return the session token to the frontend (e.g., via HTTP-only cookie or secure storage).
  </Step>

  <Step title="Client makes requests">
    The frontend sends the token in the `Authorization` header with each request.
  </Step>
</Steps>

## Step 1: Create a session

This is called from your backend using the project API key.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://synthesis.trade/api/v1/project/account/{account_id}/session" \
    -H "X-PROJECT-API-KEY: sk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678901234="
  ```

  ```json Response theme={null}
  {
      "success": true,
      "response": {
          "account_id": "01234567-89ab-cdef-0123-456789abcdef",
          "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "created_at": "2026-01-01T00:00:00",
          "expires_at": "2026-01-08T00:00:00"
      }
  }
  ```
</CodeGroup>

## Step 2: Use the session token

Pass the token from the response as a Bearer token in your client requests.

```bash theme={null}
curl -X GET "https://synthesis.trade/api/v1/wallets" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

## Refresh a session

Expire the existing session and issue a new one. This extends the user's authenticated session without requiring them to re-authenticate.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://synthesis.trade/api/v1/project/account/{account_id}/session/{session_id}/refresh" \
    -H "X-PROJECT-API-KEY: sk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678901234="
  ```

  ```json Response theme={null}
  {
      "success": true,
      "response": {
          "account_id": "01234567-89ab-cdef-0123-456789abcdef",
          "session_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "created_at": "2026-01-01T00:00:00",
          "expires_at": "2026-01-08T00:00:00"
      }
  }
  ```
</CodeGroup>

## Expire a session

Manually expire a specific session or all sessions for an account.

<CodeGroup>
  ```bash Expire one theme={null}
  curl -X POST "https://synthesis.trade/api/v1/project/account/{account_id}/session/{session_id}/expire" \
    -H "X-PROJECT-API-KEY: sk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678901234="
  ```

  ```bash Expire all theme={null}
  curl -X POST "https://synthesis.trade/api/v1/project/account/{account_id}/sessions/expire-all" \
    -H "X-PROJECT-API-KEY: sk_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678901234="
  ```
</CodeGroup>

## Available routes

All routes under `/api/v1/account/*` and `/api/v1/wallet/*` accept session tokens.

| Route                               | Method | Description                      |
| ----------------------------------- | ------ | -------------------------------- |
| `/api/v1/account/session`           | `GET`  | Get current session info         |
| `/api/v1/wallets`                   | `GET`  | List wallets                     |
| `/api/v1/wallet/pol/{id}/order`     | `POST` | Place an order                   |
| `/api/v1/wallet/pol/{id}/balance`   | `GET`  | Get wallet balance               |
| `/api/v1/wallet/pol/{id}/positions` | `GET`  | Get positions                    |
| ...                                 |        | All wallet and account endpoints |