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

# API Key Creation

# API Key Creation

This guide covers creating and managing API keys for programmatic access to the PRIME API.

## Overview

API keys enable machine-to-machine authentication without user credentials. They are ideal for:

* Automated trading bots
* Integration with external systems
* Scheduled data retrieval

## Prerequisites

* Authenticated user session (JWT token)
* 2FA enabled on the account
* Access to the email associated with the account

## API Key Properties

| Property    | Description                                              |
| ----------- | -------------------------------------------------------- |
| `id`        | Unique identifier (UUID), used as the key ID in requests |
| `label`     | Human-readable label for identification                  |
| `createdAt` | Creation timestamp                                       |

## API Key Permissions

API keys are scoped to a single sub-account with specific permissions:

| Permission | Description                |
| ---------- | -------------------------- |
| `trade`    | Place and cancel orders    |
| `withdraw` | Initiate withdrawals       |
| `deposit`  | Generate deposit addresses |

Note: Read access is implicitly granted with any API key.

## Step 1: Request Validation Code

Before creating an API key, you must request a validation code sent to your email.

**Endpoint:** `POST /api/rest/v1/users/authentication/api-keys/validation`

### Request

```bash
curl -X POST https://api.t-dx.com/api/rest/v1/users/authentication/api-keys/validation \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subAccountId": "40915c05-687c-4927-aa15-f211cea53519",
    "requestedPermissions": {
      "trade": true,
      "withdraw": false,
      "deposit": true
    }
  }'
```

### Request Fields

| Field                           | Type          | Required | Description                                 |
| ------------------------------- | ------------- | -------- | ------------------------------------------- |
| `subAccountId`                  | string (UUID) | Yes      | Sub-account the API key will have access to |
| `requestedPermissions`          | object        | Yes      | Permissions for the API key                 |
| `requestedPermissions.trade`    | boolean       | Yes      | Allow placing/canceling orders              |
| `requestedPermissions.withdraw` | boolean       | Yes      | Allow initiating withdrawals                |
| `requestedPermissions.deposit`  | boolean       | Yes      | Allow generating deposit addresses          |

### Response (200 OK)

Empty response. A validation code is sent to your email.

## Step 2: Create API Key

After receiving the validation code via email, create the API key.

**Endpoint:** `POST /api/rest/v1/users/authentication/api-keys`

### Request

```bash
curl -X POST https://api.t-dx.com/api/rest/v1/users/authentication/api-keys \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subAccountId": "40915c05-687c-4927-aa15-f211cea53519",
    "label": "Trading Bot",
    "requestedPermissions": {
      "trade": true,
      "withdraw": false,
      "deposit": true
    },
    "challenge": "123456",
    "code": "123456789"
  }'
```

### Request Fields

| Field                  | Type          | Required | Description                                 |
| ---------------------- | ------------- | -------- | ------------------------------------------- |
| `subAccountId`         | string (UUID) | Yes      | Sub-account the API key will have access to |
| `label`                | string        | No       | Human-readable label for the key            |
| `requestedPermissions` | object        | Yes      | Permissions for the API key                 |
| `challenge`            | string        | Yes      | 2FA TOTP code from your authenticator       |
| `code`                 | string        | Yes      | Validation code received via email          |

### Response (201 Created)

```json
{
  "result": {
    "id": "5321bef2-155d-40c7-aa63-5d18f5f6dc29",
    "secret": "24c7f1b400f1d0d26af3618e124e9114dccaad5f360b05491f2a553dfa13d4b0"
  }
}
```

### Response Fields

| Field           | Type          | Description                        |
| --------------- | ------------- | ---------------------------------- |
| `result.id`     | string (UUID) | API key identifier                 |
| `result.secret` | string (hex)  | Secret key in hexadecimal encoding |

**Important:** The `secret` is only returned once at creation and cannot be retrieved later. Store it securely.

## Step 3: Using API Keys

API keys use HMAC-SHA256 signatures for authentication. Include the key ID and signature in request headers.

The signature is computed over the request details using the secret (decoded from hex).

```bash
# Example headers for API key authentication
X-TDX-APIKEY: 5321bef2-155d-40c7-aa63-5d18f5f6dc29
X-TDX-SIGNATURE: <hmac-sha256-signature>
X-TDX-TIMESTAMP: <unix-timestamp>
```

## Step 4: List API Keys

**Endpoint:** `GET /api/rest/v1/users/authentication/api-keys`

### Request

```bash
curl -X GET https://api.t-dx.com/api/rest/v1/users/authentication/api-keys \
  -H "Authorization: Bearer <access-token>"
```

### Response (200 OK)

```json
{
  "apiKeys": [
    {
      "id": "5321bef2-155d-40c7-aa63-5d18f5f6dc29",
      "label": "Trading Bot",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}
```

Note: The `secret` is never returned after creation.

## Step 5: Delete API Key

**Endpoint:** `DELETE /api/rest/v1/users/authentication/api-keys/{keyId}`

### Request

```bash
curl -X DELETE https://api.t-dx.com/api/rest/v1/users/authentication/api-keys/5321bef2-155d-40c7-aa63-5d18f5f6dc29 \
  -H "Authorization: Bearer <access-token>"
```

### Response (200 OK)

Empty response on success.

## Security Best Practices

1. **Minimum Permissions**: Only grant necessary permissions
2. **Secret Storage**: Never commit secrets to version control
3. **Rotation**: Regularly delete and recreate API keys
4. **Single Purpose**: Create separate keys for different applications

## Error Scenarios

| Status | Code                | Description                                 |
| ------ | ------------------- | ------------------------------------------- |
| 400    | `INVALID_ARGUMENT`  | Invalid permissions or format               |
| 401    | `UNAUTHENTICATED`   | Invalid or expired token                    |
| 403    | `PERMISSION_DENIED` | Cannot manage API keys for this sub-account |
| 404    | `NOT_FOUND`         | API key not found                           |

## Related

* [Authentication](/prime/docs/api-usec-01-authentication) - JWT-based authentication
* [Getting Started: Authentication](/prime/docs/api-gett-authentication) - Full auth documentation