Source: https://datafa.st/docs/api/account/access-tokens/create
Markdown source: https://datafa.st/docs/api/account/access-tokens/create.md
Description: Create a dft_ account token. The raw token is returned once.

# Create access token

`POST https://datafa.st/api/v1/admin/access-tokens`

Create a new `dft_` account token with specific permissions and optional website scope. The full token is returned **once** in the response — store it securely.

You cannot grant permissions beyond what your own token has. Maximum 20 tokens per account.

## Request

#### Body parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | Label in the dashboard. Example: `"Production agent"`. Omit to store as `null`. |
| `permissions` | string[] | No | JSON array of permission strings controlling what the new token can do. Omit for full access (`["*"]`). Must not exceed your caller token — see [permission list](/docs/api/authentication#permissions). Examples: read-only `["analytics:read", "websites:read"]`; funnel manager `["funnels:read", "funnels:write", "websites:read"]`; full access `["*"]`. |
| `websiteIds` | string[] | No | Websites this token may access. Pass `[]` (default) for **all** websites on your account, or ObjectId strings to restrict. Get IDs from [List websites](/docs/api/account/websites/list). Example: `["665f0b3c4d2e1a0012345678"]`. Cannot exceed your caller token scope. |

#### Example request body

```json
{
  "name": "Analytics read-only agent",
  "permissions": ["analytics:read", "websites:read"],
  "websiteIds": ["665f0b3c4d2e1a0012345678"]
}
```

#### What to pass in `permissions`

| If you want… | Pass this array |
|---|---|
| Read analytics and visitors | `["analytics:read", "websites:read"]` |
| Send server-side goals | add `"goals:write"` |
| Record payments | add `"payments:write"` |
| Manage funnels | `["funnels:read", "funnels:write", "websites:read"]` |
| Manage alerts | `["alerts:read", "alerts:write", "websites:read"]` |
| Create other tokens / keys | add `"api-keys:read"` / `"api-keys:write"` |
| Everything | `["*"]` or omit the field |

Valid strings: `analytics:read`, `goals:read`, `goals:write`, `payments:read`, `payments:write`, `identify:write`, `websites:read`, `websites:write`, `settings:read`, `settings:write`, `funnels:read`, `funnels:write`, `alerts:read`, `alerts:write`, `team:read`, `team:write`, `api-keys:read`, `api-keys:write`, or `"*"`.

Full reference: [authentication and scopes](/docs/api/authentication#permissions).

## Response

Returns a JSON object with `status: "success"` and endpoint-specific fields in `data`.

#### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `data[]._id` | string | Token ObjectId. |
| `data[].name` | string\|null | Human-readable name for the resource or event. The exact meaning depends on the endpoint. |
| `data[].displayKey` | string | Masked token shown in the dashboard. |
| `data[].scope` | string | Token scope. Account tokens use `user`. |
| `data[].permissions` | string[] | Granted permission strings. `['*']` means full access. See [permission list](/docs/api/authentication#permissions). Example: `['analytics:read', 'websites:read']`. |
| `data[].websiteIds` | string[] | Websites this token can access. Empty array `[]` means all websites on the account. Example: `['665f0b3c4d2e1a0012345678']`. |
| `data[].lastUsedAt` | string\|null | Last usage timestamp. |
| `data[].createdAt` | string | Creation timestamp. |
| `data[].key` | string | Only returned when creating a token. Full raw token shown once. |

### Authentication

Requires a `dft_` account token with `api-keys:write`. Website API keys (`df_`) cannot call this endpoint because it manages account-level resources.

Create tokens in [Account settings → API](https://datafa.st/dashboard/settings?tab=api).

### Errors

**400** — Invalid permissions or token limit reached (max 20).

**403** — Requested scope exceeds caller token permissions.

See [API errors](/docs/api#errors) for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

## Code examples

### Example request

```bash
curl -X POST "https://datafa.st/api/v1/admin/access-tokens" \
  -H "Authorization: Bearer dft_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"Read only","permissions":["analytics:read","websites:read"],"websiteIds":["WEBSITE_ID"]}'
```

### Success response

```json
{
  "status": "success",
  "data": [{
    "_id": "665f0b3c4d2e1a0012345678",
    "name": "Read only",
    "displayKey": "dft_ab1...xyz9",
    "scope": "user",
    "permissions": ["analytics:read", "websites:read"],
    "websiteIds": ["665f0b3c4d2e1a0012345678"],
    "key": "dft_full_token_shown_once"
  }]
}
```