# API Tokens

**Page:** api/auth-tokens

[Download Raw Markdown](./api/auth-tokens.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



The API Tokens endpoints let you create and manage long-lived authentication tokens for programmatic access to the Hoody platform. Use these endpoints to issue scoped tokens with IP restrictions, expiration, and fine-grained permissions, and to manage their lifecycle (update, copy, add/remove realm bindings, delete).


Token secrets are only returned in the response body at creation or copy time. Store them securely — they cannot be retrieved later.


## List auth tokens

Returns all auth tokens for the authenticated user. Token values are not included in the response.




```bash
curl -X GET https://api.hoody.icu/api/v1/auth/tokens \
  -H "Authorization: Bearer <token>"
```




```typescript
const tokens = await client.api.authTokens.listIterator();
```




### Response




```json
{
  "statusCode": 200,
  "message": "Auth tokens retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "alias": "Production API Key",
      "prefix": "hdy_",
      "ip_whitelist": ["192.168.1.0/24", "10.0.0.1"],
      "realm_ids": [],
      "allow_no_realm": true,
      "expires_at": "2025-12-31T23:59:59.000Z",
      "is_enabled": true,
      "vault_access": true,
      "event_access": true,
      "last_used_at": "2025-10-28T12:00:00.000Z",
      "last_used_ip": "198.51.100.1",
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T14:45:00.000Z"
    },
    {
      "id": "507f1f77bcf86cd799439022",
      "alias": "Development Token",
      "prefix": "hdy_",
      "ip_whitelist": ["*"],
      "realm_ids": ["507f1f77bcf86cd799439011"],
      "allow_no_realm": false,
      "expires_at": null,
      "is_enabled": true,
      "vault_access": false,
      "event_access": true,
      "last_used_at": null,
      "last_used_ip": null,
      "created_at": "2025-01-10T08:00:00.000Z",
      "updated_at": "2025-01-10T08:00:00.000Z"
    }
  ]
}
```




```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as "Bearer &lt;token&gt;" |
| `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
| `TOKEN_EXPIRED` | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |




## Get auth token by ID

Returns details of a specific auth token. The token value is not included in the response.




```bash
curl -X GET https://api.hoody.icu/api/v1/auth/tokens/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer <token>"
```




```typescript
const token = await client.api.authTokens.get({ id: "507f1f77bcf86cd799439011" });
```




### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Unique identifier of the token |

### Response




```json
{
  "statusCode": 200,
  "message": "Auth token retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "alias": "Production API Key",
    "prefix": "hdy_",
    "ip_whitelist": ["192.168.1.0/24", "10.0.0.1"],
    "realm_ids": [],
    "allow_no_realm": true,
    "expires_at": "2025-12-31T23:59:59.000Z",
    "is_enabled": true,
    "vault_access": true,
    "event_access": true,
    "last_used_at": "2025-10-28T12:00:00.000Z",
    "last_used_ip": "198.51.100.1",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T14:45:00.000Z"
  }
}
```




```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid ID format"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_ID_FORMAT` | Invalid ID format | The provided ID must be a 24-character hexadecimal string | Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f) |




```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as "Bearer &lt;token&gt;" |
| `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
| `TOKEN_EXPIRED` | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |




```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Authentication token not found"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `TOKEN_NOT_FOUND` | Authentication token not found | The requested authentication token does not exist or has been deleted | Verify the token ID is correct and that the token still exists |




## Get current auth token details

Returns metadata, permissions, and realm restrictions for the currently authenticated auth token. This endpoint is allowed on the base `api.hoody.icu` domain for realm-scoped tokens to bootstrap realm discovery.




```bash
curl -X GET https://api.hoody.icu/api/v1/auth/tokens/me \
  -H "Authorization: Bearer <token>"
```




```typescript
const current = await client.api.authTokens.getCurrent();
```




### Response




```json
{
  "statusCode": 200,
  "message": "Current auth token retrieved successfully",
  "data": {
    "token": {
      "id": "507f1f77bcf86cd799439011",
      "alias": "External Customer Token",
      "prefix": "hdy_",
      "ip_whitelist": ["*"],
      "realm_ids": ["507f1f77bcf86cd799439012"],
      "allow_no_realm": false,
      "permissions": {
        "containers": {
          "read": true,
          "create": true
        },
        "resources": {
          "realms": true
        }
      },
      "expires_at": null,
      "is_enabled": true,
      "vault_access": false,
      "event_access": true,
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z"
    },
    "restrictions": {
      "has_realm_restrictions": true,
      "requires_realm_scope": true,
      "allowed_realm_ids": ["507f1f77bcf86cd799439012"],
      "allow_no_realm": false,
      "active_realm_id": "507f1f77bcf86cd799439012"
    }
  }
}
```




```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as "Bearer &lt;token&gt;" |
| `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
| `TOKEN_EXPIRED` | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |




```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INSUFFICIENT_PERMISSIONS` | Insufficient permissions | You do not have the required permissions to perform this action | Contact the resource owner or administrator to request access |




## Get auth token public profile by public key

Resolves and retrieves an auth token's public profile storage by ED25519 public key.




```bash
curl -X GET https://api.hoody.icu/api/v1/auth/tokens/public-profiles/a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234 \
  -H "Authorization: Bearer <token>"
```




```typescript
const profile = await client.api.authTokens.getPublicProfile({
  public_key: "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234"
});
```




### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `public_key` | path | string | Yes | ED25519 public key to resolve |

### Response




```json
{
  "statusCode": 200,
  "message": "Public profile retrieved successfully",
  "data": {
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "public_storage": {
      "display_name": "Acme Integrations",
      "website": "https://example.com"
    }
  }
}
```




```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid public key format"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input parameters | One or more request parameters failed validation | Check the error message for specific field requirements and correct your input |
| `INVALID_PUBLIC_KEY_FORMAT` | Invalid public key format | Public key must be exactly 64 hexadecimal characters (ED25519 format) | Provide a valid 64-character ED25519 public key in hexadecimal format |




```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as "Bearer &lt;token&gt;" |
| `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
| `TOKEN_EXPIRED` | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |




```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Authentication token not found"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `TOKEN_NOT_FOUND` | Authentication token not found | The requested authentication token does not exist or has been deleted | Verify the token ID is correct and that the token still exists |




## Create a new auth token

Creates a new long-term authentication token with optional IP restrictions, expiration, and fine-grained permissions.




```bash
curl -X POST https://api.hoody.icu/api/v1/auth/tokens \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "Production API Key",
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "public_storage": {
      "display_name": "Production Integrations",
      "tier": "gold"
    },
    "ip_whitelist": ["192.168.1.0/24", "10.0.0.1"],
    "vault_access": true,
    "expires_at": 1767225599000
  }'
```




```typescript
const result = await client.api.authTokens.create({
  data: {
    alias: "Production API Key",
    public_key: "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    public_storage: {
      display_name: "Production Integrations",
      tier: "gold"
    },
    ip_whitelist: ["192.168.1.0/24", "10.0.0.1"],
    vault_access: true,
    expires_at: 1767225599000
  }
});
```




### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `alias` | string | No | User-friendly alias. Allowed characters: letters, numbers, spaces, underscores, hyphens. If omitted, a random animal name is generated. |
| `public_key` | string \| null | No | ED25519 public key (64 hex chars) or `null` to clear. |
| `public_storage` | object \| null | No | Public JSON profile storage (max 64KB) or `null` to clear. |
| `ip_whitelist` | array \| string | No | Array of IPv4 addresses/CIDR ranges, comma-separated string, or `*` wildcard. Defaults to `*`. |
| `permission_template` | string | No | Permission template to apply (`full_access`, `external_customer`, `dev_team`, `finance_team`, `read_only`). Takes precedence over `permissions`. |
| `permissions` | object | No | Fine-grained permission map. Missing paths default to `false`. |
| `realm_ids` | array | No | Realm IDs to restrict this token to. |
| `allow_no_realm` | boolean | No | Whether the token can be used without a realm scope. Default: `true`. |
| `vault_access` | boolean | No | Whether the token can access user vault endpoints. Default: `false`. |
| `event_access` | boolean | No | Whether the token can access event streams. Default: `true`. |
| `expires_at` | string \| number | No | ISO 8601 date, Unix timestamp, `today`, or `tomorrow`. |
| `otp_code` | string | No | TOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled and authenticating via JWT. |

### Response




```json
{
  "statusCode": 201,
  "message": "Auth token created successfully",
  "data": {
    "token": "hdy_a1b2c3d4e5f67890abcdef1234567890",
    "id": "507f1f77bcf86cd799439011",
    "alias": "Production API Key",
    "prefix": "hdy_",
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "public_storage": {
      "display_name": "Production Integrations",
      "tier": "gold"
    },
    "ip_whitelist": ["192.168.1.0/24", "10.0.0.1"],
    "realm_ids": [],
    "allow_no_realm": true,
    "permissions": {
      "containers": {
        "read": true
      }
    },
    "expires_at": "2025-12-31T23:59:59.000Z",
    "is_enabled": true,
    "vault_access": true,
    "event_access": true,
    "last_used_at": null,
    "last_used_ip": null,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z"
  }
}
```




```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input parameters | One or more request parameters failed validation | Check the error message for specific field requirements and correct your input |
| `MISSING_REQUIRED_FIELD` | Required field missing | One or more required fields are missing from the request | Include all required fields as specified in the API documentation |
| `OTP_REQUIRED` | 2FA verification required | This operation requires 2FA verification because your account has 2FA enabled | Provide an `otp_code` field with a valid TOTP code or backup code |
| `INVALID_ALIAS_FORMAT` | Invalid alias format | Token alias must contain only letters, numbers, spaces, underscores, and hyphens | Use only allowed characters: letters (a-z, A-Z), numbers (0-9), spaces, underscores (`_`), and hyphens (`-`) |
| `INVALID_IP_FORMAT` | Invalid IP address format | IP whitelist must contain valid IPv4 addresses or CIDR ranges | Provide valid IPv4 addresses (e.g., `192.168.1.1`) or CIDR ranges (e.g., `192.168.1.0/24`), or use `*` for all IPs |
| `INVALID_REALM_ID_FORMAT` | Invalid realm ID format | Realm IDs must be 24-character hexadecimal strings | Ensure all realm IDs are valid 24-character hex strings (e.g., `507f1f77bcf86cd799439011`) |
| `INVALID_EXPIRATION_FORMAT` | Invalid expiration format | Expiration must be an ISO 8601 date, Unix timestamp, `today`, `tomorrow`, or null | Use a valid date format: ISO 8601 string, Unix timestamp (seconds/milliseconds), `today`, `tomorrow`, or null for non-expiring |
| `INVALID_PUBLIC_KEY_FORMAT` | Invalid public key format | Public key must be exactly 64 hexadecimal characters (ED25519 format) | Provide a valid 64-character ED25519 public key in hexadecimal format |
| `PUBLIC_STORAGE_TOO_LARGE` | Public storage exceeds size limit | `public_storage` must not exceed 64KB serialized JSON | Reduce the size of the public storage payload and retry |
| `EXPIRATION_IN_PAST` | Expiration date in the past | The expiration date cannot be in the past | Provide a future date for token expiration |




```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as "Bearer &lt;token&gt;" |
| `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
| `TOKEN_EXPIRED` | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |




```json
{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Token alias already exists"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `DUPLICATE_ALIAS` | Token alias already exists | You already have an authentication token with this alias | Choose a different unique alias for this token |




## Add realm to auth token

Atomically adds a realm ID to an auth token. Idempotent — if the realm is already present, returns success without modification.




```bash
curl -X POST https://api.hoody.icu/api/v1/auth/tokens/507f1f77bcf86cd799439011/add-realm \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "realm_id": "507f1f77bcf86cd799439012"
  }'
```




```typescript
const result = await client.api.authTokens.addRealm({
  id: "507f1f77bcf86cd799439011",
  data: { realm_id: "507f1f77bcf86cd799439012" }
});
```




### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Auth token ID |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `realm_id` | string | Yes | Realm ID to add to the token |
| `otp_code` | string | No | TOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled and authenticating via JWT. |

### Response




```json
{
  "statusCode": 200,
  "message": "Realm added to auth token successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "alias": "External Customer Token",
    "prefix": "hdy_",
    "ip_whitelist": ["*"],
    "realm_ids": ["507f1f77bcf86cd799439012", "507f1f77bcf86cd799439013"],
    "allow_no_realm": false,
    "permissions": {
      "containers": { "read": true }
    },
    "expires_at": null,
    "is_enabled": true,
    "vault_access": false,
    "event_access": true,
    "last_used_at": null,
    "last_used_ip": null,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T15:00:00.000Z"
  }
}
```




```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid realm ID format"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `OTP_REQUIRED` | 2FA verification required | This operation requires 2FA verification because your account has 2FA enabled | Provide an `otp_code` field with a valid TOTP code or backup code |
| `INVALID_REALM_ID_FORMAT` | Invalid realm ID format | Realm IDs must be 24-character hexadecimal strings | Ensure all realm IDs are valid 24-character hex strings (e.g., `507f1f77bcf86cd799439011`) |




```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}
```




```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Authentication token not found"
}
```




## Copy auth token

Copies an existing auth token's configuration (permissions, realm restrictions, IP whitelist) into a new token with a new secret value.




```bash
curl -X POST https://api.hoody.icu/api/v1/auth/tokens/507f1f77bcf86cd799439011/copy \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "Production API Key Copy"
  }'
```




```typescript
const result = await client.api.authTokens.copy({
  id: "507f1f77bcf86cd799439011",
  data: { alias: "Production API Key Copy" }
});
```




### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Unique identifier of the token |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `alias` | string | No | Optional alias for the copied token. If omitted, a deterministic alias like `"&lt;source&gt; copy"` is generated. |
| `expires_at` | string \| number \| null | No | ISO 8601 date, Unix timestamp, `today`, `tomorrow`, or `null` for non-expiring. Defaults to source expiration. |
| `otp_code` | string | No | TOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled and authenticating via JWT. |

### Response




```json
{
  "statusCode": 201,
  "message": "Auth token copied successfully",
  "data": {
    "token": "hdy_f0e1d2c3b4a5968778695a4b3c2d1e0f1234567890abcdef",
    "id": "507f1f77bcf86cd799439099",
    "alias": "Production API Key Copy",
    "prefix": "hdy_",
    "ip_whitelist": ["192.168.1.0/24", "10.0.0.1"],
    "realm_ids": ["507f1f77bcf86cd799439011"],
    "allow_no_realm": false,
    "permissions": {
      "containers": { "read": true }
    },
    "expires_at": "2025-12-31T23:59:59.000Z",
    "is_enabled": true,
    "vault_access": true,
    "event_access": true,
    "last_used_at": null,
    "last_used_ip": null,
    "created_at": "2025-01-20T08:30:00.000Z",
    "updated_at": "2025-01-20T08:30:00.000Z"
  }
}
```




```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input parameters | One or more request parameters failed validation | Check the error message for specific field requirements and correct your input |
| `INVALID_ID_FORMAT` | Invalid ID format | The provided ID must be a 24-character hexadecimal string | Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f) |
| `OTP_REQUIRED` | 2FA verification required | This operation requires 2FA verification because your account has 2FA enabled | Provide an `otp_code` field with a valid TOTP code or backup code |
| `INVALID_ALIAS_FORMAT` | Invalid alias format | Token alias must contain only letters, numbers, spaces, underscores, and hyphens | Use only allowed characters: letters (a-z, A-Z), numbers (0-9), spaces, underscores (`_`), and hyphens (`-`) |
| `INVALID_EXPIRATION_FORMAT` | Invalid expiration format | Expiration must be an ISO 8601 date, Unix timestamp, `today`, `tomorrow`, or null | Use a valid date format: ISO 8601 string, Unix timestamp (seconds/milliseconds), `today`, `tomorrow`, or null for non-expiring |
| `EXPIRATION_IN_PAST` | Expiration date in the past | The expiration date cannot be in the past | Provide a future date for token expiration |




```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as "Bearer &lt;token&gt;" |
| `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
| `TOKEN_EXPIRED` | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |




```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INSUFFICIENT_PERMISSIONS` | Insufficient permissions | You do not have the required permissions to perform this action | Contact the resource owner or administrator to request access |
| `ACCOUNT_BANNED` | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |




```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Authentication token not found"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `TOKEN_NOT_FOUND` | Authentication token not found | The requested authentication token does not exist or has been deleted | Verify the token ID is correct and that the token still exists |




```json
{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Token alias already exists"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `DUPLICATE_ALIAS` | Token alias already exists | You already have an authentication token with this alias | Choose a different unique alias for this token |




## Remove realm from auth token

Atomically removes a realm ID from an auth token. Idempotent — if the realm is not present, returns success without modification.




```bash
curl -X POST https://api.hoody.icu/api/v1/auth/tokens/507f1f77bcf86cd799439011/remove-realm \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "realm_id": "507f1f77bcf86cd799439012"
  }'
```




```typescript
const result = await client.api.authTokens.removeRealm({
  id: "507f1f77bcf86cd799439011",
  data: { realm_id: "507f1f77bcf86cd799439012" }
});
```




### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Auth token ID |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `realm_id` | string | Yes | Realm ID to remove from the token |
| `otp_code` | string | No | TOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled and authenticating via JWT. |

### Response




```json
{
  "statusCode": 200,
  "message": "Realm removed from auth token successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "alias": "External Customer Token",
    "prefix": "hdy_",
    "ip_whitelist": ["*"],
    "realm_ids": [],
    "allow_no_realm": false,
    "permissions": {
      "containers": { "read": true }
    },
    "expires_at": null,
    "is_enabled": true,
    "vault_access": false,
    "event_access": true,
    "last_used_at": null,
    "last_used_ip": null,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T15:10:00.000Z"
  }
}
```




```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid realm ID format"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `OTP_REQUIRED` | 2FA verification required | This operation requires 2FA verification because your account has 2FA enabled | Provide an `otp_code` field with a valid TOTP code or backup code |
| `INVALID_REALM_ID_FORMAT` | Invalid realm ID format | Realm IDs must be 24-character hexadecimal strings | Ensure all realm IDs are valid 24-character hex strings (e.g., `507f1f77bcf86cd799439011`) |




```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}
```




```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Authentication token not found"
}
```




## Update auth token

Updates an existing auth token's alias, public key/profile storage, IP restrictions, expiration, enabled status, permissions, or realm bindings.




```bash
curl -X PATCH https://api.hoody.icu/api/v1/auth/tokens/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "Updated Production Key",
    "ip_whitelist": ["*"],
    "vault_access": false,
    "expires_at": null,
    "is_enabled": false
  }'
```




```typescript
const updated = await client.api.authTokens.update({
  id: "507f1f77bcf86cd799439011",
  data: {
    alias: "Updated Production Key",
    ip_whitelist: ["*"],
    vault_access: false,
    expires_at: null,
    is_enabled: false
  }
});
```




### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Unique identifier of the token to update |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `alias` | string | No | User-friendly alias. Allowed characters: letters, numbers, spaces, underscores, hyphens. |
| `public_key` | string \| null | No | ED25519 public key (64 hex chars) or `null` to clear. |
| `public_storage` | object \| null | No | Public JSON profile storage (max 64KB) or `null` to clear. |
| `ip_whitelist` | array \| string | No | Array of IPv4 addresses/CIDR ranges, comma-separated string, or `*` wildcard. |
| `permissions` | object | No | Fine-grained permission map. Missing paths default to `false`. |
| `realm_ids` | array | No | Realm IDs to restrict this token to. |
| `allow_no_realm` | boolean | No | Whether the token can be used without a realm scope. |
| `vault_access` | boolean | No | Whether the token can access user vault endpoints. |
| `event_access` | boolean | No | Whether the token can access event streams and event history. |
| `expires_at` | string \| number \| null | No | ISO 8601 date, Unix timestamp, `today`, `tomorrow`, or `null` for non-expiring. |
| `is_enabled` | boolean | No | Enable or disable the token. |
| `otp_code` | string | No | TOTP code (6 digits) or backup code (10 alphanumeric). Required if 2FA is enabled and authenticating via JWT. |

### Response




```json
{
  "statusCode": 200,
  "message": "Auth token updated successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "alias": "Updated Production Key",
    "prefix": "hdy_",
    "ip_whitelist": ["*"],
    "realm_ids": [],
    "allow_no_realm": true,
    "permissions": {
      "containers": { "read": true }
    },
    "expires_at": null,
    "is_enabled": false,
    "vault_access": false,
    "event_access": true,
    "last_used_at": "2025-10-28T12:00:00.000Z",
    "last_used_ip": "198.51.100.1",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T14:45:00.000Z"
  }
}
```




```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input parameters | One or more request parameters failed validation | Check the error message for specific field requirements and correct your input |
| `INVALID_ID_FORMAT` | Invalid ID format | The provided ID must be a 24-character hexadecimal string | Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f) |
| `OTP_REQUIRED` | 2FA verification required | This operation requires 2FA verification because your account has 2FA enabled | Provide an `otp_code` field with a valid TOTP code or backup code |
| `INVALID_ALIAS_FORMAT` | Invalid alias format | Token alias must contain only letters, numbers, spaces, underscores, and hyphens | Use only allowed characters: letters (a-z, A-Z), numbers (0-9), spaces, underscores (`_`), and hyphens (`-`) |
| `INVALID_IP_FORMAT` | Invalid IP address format | IP whitelist must contain valid IPv4 addresses or CIDR ranges | Provide valid IPv4 addresses (e.g., `192.168.1.1`) or CIDR ranges (e.g., `192.168.1.0/24`), or use `*` for all IPs |
| `INVALID_REALM_ID_FORMAT` | Invalid realm ID format | Realm IDs must be 24-character hexadecimal strings | Ensure all realm IDs are valid 24-character hex strings (e.g., `507f1f77bcf86cd799439011`) |
| `INVALID_EXPIRATION_FORMAT` | Invalid expiration format | Expiration must be an ISO 8601 date, Unix timestamp, `today`, `tomorrow`, or null | Use a valid date format: ISO 8601 string, Unix timestamp (seconds/milliseconds), `today`, `tomorrow`, or null for non-expiring |
| `INVALID_PUBLIC_KEY_FORMAT` | Invalid public key format | Public key must be exactly 64 hexadecimal characters (ED25519 format) | Provide a valid 64-character ED25519 public key in hexadecimal format |
| `PUBLIC_STORAGE_TOO_LARGE` | Public storage exceeds size limit | `public_storage` must not exceed 64KB serialized JSON | Reduce the size of the public storage payload and retry |
| `EXPIRATION_IN_PAST` | Expiration date in the past | The expiration date cannot be in the past | Provide a future date for token expiration |




```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as "Bearer &lt;token&gt;" |
| `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
| `TOKEN_EXPIRED` | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |




```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Authentication token not found"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `TOKEN_NOT_FOUND` | Authentication token not found | The requested authentication token does not exist or has been deleted | Verify the token ID is correct and that the token still exists |




```json
{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Token alias already exists"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `DUPLICATE_ALIAS` | Token alias already exists | You already have an authentication token with this alias | Choose a different unique alias for this token |




## Update current auth token public profile

Updates the current auth token's `public_key` and `public_storage` payload. Requires the `resources.auth_token_public_profile` permission on the auth token.




```bash
curl -X PATCH https://api.hoody.icu/api/v1/auth/tokens/me/public-profile \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "public_storage": {
      "username_hint": "acme-team",
      "avatar": "https://cdn.example.com/avatar.png"
    }
  }'
```




```typescript
const updated = await client.api.authTokens.updatePublicProfile({
  data: {
    public_key: "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    public_storage: {
      username_hint: "acme-team",
      avatar: "https://cdn.example.com/avatar.png"
    }
  }
});
```




### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `public_key` | string \| null | No | ED25519 public key (64 hex chars) or `null` to clear. |
| `public_storage` | object \| null | No | Public JSON profile storage (max 64KB) or `null` to clear. |

At least one of `public_key` or `public_storage` must be provided.

### Response




```json
{
  "statusCode": 200,
  "message": "Public profile updated successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "alias": "External Customer Token",
    "prefix": "hdy_",
    "public_key": "a1b2c3d4e5f6789012345678901234567890abcdefabcdefabcdefabcdef1234",
    "public_storage": {
      "username_hint": "acme-team",
      "avatar": "https://cdn.example.com/avatar.png"
    },
    "ip_whitelist": ["*"],
    "realm_ids": ["507f1f77bcf86cd799439012"],
    "allow_no_realm": false,
    "permissions": {
      "containers": { "read": true }
    },
    "expires_at": null,
    "is_enabled": true,
    "vault_access": false,
    "event_access": true,
    "last_used_at": null,
    "last_used_ip": null,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T15:00:00.000Z"
  }
}
```




```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input parameters | One or more request parameters failed validation | Check the error message for specific field requirements and correct your input |
| `INVALID_PUBLIC_KEY_FORMAT` | Invalid public key format | Public key must be exactly 64 hexadecimal characters (ED25519 format) | Provide a valid 64-character ED25519 public key in hexadecimal format |
| `PUBLIC_STORAGE_TOO_LARGE` | Public storage exceeds size limit | `public_storage` must not exceed 64KB serialized JSON | Reduce the size of the public storage payload and retry |




```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as "Bearer &lt;token&gt;" |
| `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
| `TOKEN_EXPIRED` | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |




```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INSUFFICIENT_PERMISSIONS` | Insufficient permissions | You do not have the required permissions to perform this action | Contact the resource owner or administrator to request access |




## Delete auth token

Deletes an auth token. Once deleted, the token can no longer be used for authentication.




```bash
curl -X DELETE https://api.hoody.icu/api/v1/auth/tokens/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer <token>"
```




```typescript
await client.api.authTokens.delete({ id: "507f1f77bcf86cd799439011" });
```




### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Unique identifier of the token |

### Response




```json
{
  "statusCode": 200,
  "message": "Auth token deleted successfully"
}
```




```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid ID format"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_ID_FORMAT` | Invalid ID format | The provided ID must be a 24-character hexadecimal string | Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f) |




```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MISSING_TOKEN` | Authentication token missing | No authentication token was provided in the request | Include a valid JWT token in the Authorization header as "Bearer &lt;token&gt;" |
| `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid | Obtain a new token by logging in again or using a valid auth token |
| `TOKEN_EXPIRED` | Authentication token expired | The provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |




```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INSUFFICIENT_PERMISSIONS` | Insufficient permissions | You do not have the required permissions to perform this action | Contact the resource owner or administrator to request access |
| `ACCOUNT_BANNED` | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |




```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Authentication token not found"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `TOKEN_NOT_FOUND` | Authentication token not found | The requested authentication token does not exist or has been deleted | Verify the token ID is correct and that the token still exists |