> 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.

# Authentication Flow

# Authentication

This guide covers the complete authentication flow for accessing the PRIME API.

## Overview

The platform supports two authentication methods:

1. **JWT Bearer Tokens** - For user sessions (web/mobile clients)
2. **API Keys** - For programmatic access (see [API Key Creation](/prime/docs/api-usec-02-api-key-creation))

## Prerequisites

* Valid user credentials (username/password)
* TOTP authenticator configured (if 2FA is enabled)

## Step 1: Login

Authenticate with username and password.

**Endpoint:** `POST /api/rest/v1/users/authentication/login`

### Request

```bash
curl -X POST https://api.t-dx.com/api/rest/v1/users/authentication/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user@example.com",
    "password": "your-password"
  }'
```

### Request Fields

| Field            | Type   | Required | Description                                               |
| ---------------- | ------ | -------- | --------------------------------------------------------- |
| `username`       | string | Yes      | Username of the user                                      |
| `password`       | string | Yes      | Password of the user                                      |
| `challenge`      | string | No       | TOTP code if 2FA is enabled for the user                  |
| `recaptchaToken` | string | No       | reCAPTCHA token if required                               |
| `deviceId`       | string | No       | Optional device identifier to override a previous session |

### Response (200 OK)

```json
{
  "result": {
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "refreshToken": "5321bef2-155d-40c7-aa63-5d18f5f6dc29",
    "accessExpiresAt": "2024-01-15T11:30:00Z",
    "sessionExpiresAt": "2024-01-22T10:30:00Z"
  }
}
```

### Response Fields

| Field                     | Type          | Description                       |
| ------------------------- | ------------- | --------------------------------- |
| `result.accessToken`      | string        | JWT access token for API requests |
| `result.refreshToken`     | string (UUID) | Token to refresh the session      |
| `result.accessExpiresAt`  | timestamp     | When the access token expires     |
| `result.sessionExpiresAt` | timestamp     | When the session expires          |

## Step 2: Login with 2FA

If 2FA is enabled, include the TOTP code in the `challenge` field.

### Request

```bash
curl -X POST https://api.t-dx.com/api/rest/v1/users/authentication/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user@example.com",
    "password": "your-password",
    "challenge": "123456"
  }'
```

The response is the same as a successful login without 2FA.

## Step 3: Using the Access Token

Include the access token in the `Authorization` header for all subsequent API requests.

```bash
curl -X GET https://api.t-dx.com/api/rest/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
```

## Step 4: Refreshing Tokens

Before the access token expires, use the refresh token to obtain a new one.

**Endpoint:** `POST /api/rest/v1/users/authentication/refresh`

### Request

```bash
curl -X POST https://api.t-dx.com/api/rest/v1/users/authentication/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "5321bef2-155d-40c7-aa63-5d18f5f6dc29"
  }'
```

### Request Fields

| Field          | Type          | Required | Description              |
| -------------- | ------------- | -------- | ------------------------ |
| `refreshToken` | string (UUID) | Yes      | Session token to refresh |

### Response (200 OK)

```json
{
  "result": {
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "refreshToken": "5321bef2-155d-40c7-aa63-5d18f5f6dc29",
    "accessExpiresAt": "2024-01-15T12:30:00Z",
    "sessionExpiresAt": "2024-01-22T10:30:00Z"
  }
}
```

## Step 5: Logout

Invalidate the current session or all sessions.

**Endpoint:** `POST /api/rest/v1/users/authentication/logout`

### Request (Logout specific session)

```bash
curl -X POST https://api.t-dx.com/api/rest/v1/users/authentication/logout \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "5321bef2-155d-40c7-aa63-5d18f5f6dc29"
  }'
```

### Request (Logout all sessions)

```bash
curl -X POST https://api.t-dx.com/api/rest/v1/users/authentication/logout \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Request Fields

| Field          | Type          | Required | Description                                                               |
| -------------- | ------------- | -------- | ------------------------------------------------------------------------- |
| `refreshToken` | string (UUID) | No       | Specific session to invalidate. If omitted, all sessions are invalidated. |

### Response (200 OK)

Empty response on success.

## Error Scenarios

| Status | Code                   | Description                             |
| ------ | ---------------------- | --------------------------------------- |
| 401    | `UNAUTHENTICATED`      | Invalid credentials or missing 2FA code |
| 403    | `ACCOUNT_IS_SUSPENDED` | Account suspended                       |
| 429    | `RESOURCE_EXHAUSTED`   | Too many login attempts                 |

## Related

* [API Key Creation](/prime/docs/api-usec-02-api-key-creation) - Create API keys for programmatic access
* [Getting Started: Authentication](/prime/docs/api-gett-authentication) - Detailed auth documentation