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

# Issue API token

> Create a long-lived API token.

```http theme={null}
POST /api/v1/auth/tokens
```

Create a long-lived token shaped `ms_<prefix>_<secret>`. The plaintext token is returned **once**,
so store the token immediately.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST http://localhost:5080/api/v1/auth/tokens \
    -H "authorization: Bearer $MS_JWT" \
    -H 'content-type: application/json' \
    -d '{
      "name": "collector-production",
      "role_id": "<organization-role-id>",
      "expires_in_days": 90
    }'
  ```
</RequestExample>

`role_id` is optional and defaults to the organization's default API-token role. The selected role
cannot grant permissions the caller does not have. Omit `expires_in_days` for a non-expiring token;
explicit values are clamped to 1–1825 days. Creating tokens requires `api_tokens.manage`.

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "<token-id>",
    "prefix": "a1b2c3",
    "token": "ms_a1b2c3_d4e5f6g7h8i9...",
    "role_id": "<organization-role-id>",
    "role_key": "viewer",
    "role_name": "Viewer",
    "expires_at_micros": 1735689600000000,
    "created_at_micros": 1727913600000000
  }
  ```
</ResponseExample>