# Create a named token (owner only). Returns the token once.

`POST /datanotes/tokens/create/` (operation `tokens_create`)

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `X-Datanotes-Actor` | header | `string` | no | JSON: on whose behalf the write is made, recorded in the journal (`harness`, `model`, `session`). |

## Request body

`application/json`

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | `string` | yes |  | Kebab-case; the journal records it as `auth`. `owner` is reserved. |
| `description` | `string` | no |  |  |
| `write` | `string[]` | no |  | Tables the token may write: catalog.schema.table, catalog.schema.*, catalog.* or *. |
| `ddl` | `boolean` | no |  | May the token change the schema? |
| `maintain` | `boolean` | no |  | May the token also undo, restore, vacuum, configure and rebuild the semantic index? (For an agent's own token.) |
| `autolink` | `boolean` | no |  | Automatic links of the token's writes that pass no `autolink`: false for a sync program's token. Absent: the database's `autolink` setting. |

## Responses

| Status | Description | Body |
| --- | --- | --- |
| 200 | Done. | `object` (application/json) |
| 400 | Bad input: the body is not a JSON object, or an argument is unknown, missing or of the wrong type. | `Error` (application/json) |
| 401 | Missing or wrong bearer token. | `Error` (application/json) |
| 403 | A named token beyond its permissions (the engine's administration, tables outside its `write` patterns, schema changes without `ddl`). | `Error` (application/json) |
| 500 | Unexpected error. | `Error` (application/json) |

The schemas named here are in [openapi.json](https://datanotes.dev/openapi.json) (`components.schemas`).