> This page is for Taurus PRIME.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://taurushq.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://taurushq.ferndocs.com/_mcp/server.

# Sessions & Authentication

# Sessions & Authentication

Authentication domain handles user login, session management, and API key operations.

## Key Concepts

* **Session**: Server-side state tied to a refresh token (UUID)
* **Access Token**: Short-lived JWT for API requests
* **Refresh Token**: Long-lived session identifier for token renewal
* **API Key**: Credentials for programmatic access

## Endpoints Overview

| Endpoint                | Method | Description                   |
| ----------------------- | ------ | ----------------------------- |
| `/auth/login`           | POST   | Authenticate with credentials |
| `/auth/logout`          | POST   | Invalidate session            |
| `/auth/refresh`         | POST   | Get new access token          |
| `/auth/mfa/verify`      | POST   | Complete MFA challenge        |
| `/auth/mfa/setup`       | POST   | Initialize MFA setup          |
| `/auth/password/reset`  | POST   | Request password reset        |
| `/auth/password/change` | POST   | Change password               |
| `/api-keys`             | GET    | List API keys                 |
| `/api-keys`             | POST   | Create API key                |
| `/api-keys/{id}`        | DELETE | Revoke API key                |

## Session Flow

```
Login → [MFA if enabled] → Access Token + Session Token
                                   │
                                   ▼
                          Use Access Token in requests
                                   │
                                   ▼ (before expiry)
                          Refresh → New Access Token
```

## MFA States

| State          | Description                                  |
| -------------- | -------------------------------------------- |
| Not Configured | MFA not set up                               |
| Setup Pending  | TOTP secret generated, awaiting confirmation |
| Enabled        | MFA required on login                        |

## API Key Permissions

API keys can have a subset of user permissions:

| Permission | Allows                     |
| ---------- | -------------------------- |
| `read`     | View data                  |
| `trade`    | Place/cancel orders        |
| `withdraw` | Initiate withdrawals       |
| `deposit`  | Generate deposit addresses |

## Related Use Cases

* [Authentication](/prime/docs/api-usec-01-authentication)
* [API Key Creation](/prime/docs/api-usec-02-api-key-creation)