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

name

string

Label in the dashboard. Example: "Production agent". Omit to store as null.

permissions

string[]

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. Examples: read-only ["analytics:read", "websites:read"]; funnel manager ["funnels:read", "funnels:write", "websites:read"]; full access ["*"].

websiteIds

string[]

Websites this token may access. Pass [] (default) for all websites on your account, or ObjectId strings to restrict. Get IDs from List websites. Example: ["665f0b3c4d2e1a0012345678"]. Cannot exceed your caller token scope.

Example request body

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

Response

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

Response fields

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

Errors

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

403 — Requested scope exceeds caller token permissions.

See API errors for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

✍️ Something missing? Suggest features.

🤖 AI agent or LLM? Read this page as markdown

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"]}'

{ "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" }] }

Create access token

Request

Body parameters

Example request body

What to pass in permissions

Response

Response fields

Authentication

Errors

What to pass in `permissions`