# Create an API token

`POST /v1/workspaces/{workspaceId}/api-tokens`

Creates a personal API token for one workspace. The secret is returned once; send it as `Authorization: Bearer <secret>` to /v1 operation routes or /mcp. It acts as you, limited to this workspace and the given scopes (default: read and write).

Needs a signed-in session; API and OAuth tokens get 403.

## Request

```bash
curl -X POST "https://api.lydie.co/v1/workspaces/01JCQ3TZ0WJ8K4M2X7T9R6N1PA/api-tokens" \
  -H "Authorization: Bearer $LYDIE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sync script",
    "scopes": [
      "docs:read"
    ]
  }'
```

## Path parameters

- `workspaceId` (string, required): (1–64 chars)

## Body

- `name` (string, required): (1–100 chars)
- `scopes` (string[], optional): Default: `["docs:read","docs:write"]`. (≥ 1 items)
- `expiresInDays` (integer, optional): (1–3650)

## Response

- `token` (ApiToken, required)
  - `id` (string, required): (1–64 chars)
  - `workspaceId` (string, required): (1–64 chars)
  - `name` (string, required)
  - `prefix` (string, required): The secret's first characters, to recognise it.
  - `scopes` (string[], required)
  - `createdAt` (string, required)
  - `lastUsedAt` (string, required, nullable)
  - `expiresAt` (string, required, nullable)
- `secret` (string, required)

```json
{
  "token": {
    "id": "string",
    "workspaceId": "01JCQ3TZ0WJ8K4M2X7T9R6N1PA",
    "name": "Notes",
    "prefix": "string",
    "scopes": [
      "docs:read"
    ],
    "createdAt": "string",
    "lastUsedAt": null,
    "expiresAt": null
  },
  "secret": "string"
}
```

Errors use the envelope described at https://developers.lydie.co/errors.md.