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

# Account and settings API

> Sign in and out, change your password, read your identity, and manage workspace settings.

These endpoints cover your session (sign in, sign out, change password), who you are (`/api/me`), the first-run guide, workspace-wide settings, Composio toolkits, and the free TokenOps assessment. The dashboard calls all of them. The `nasiko` CLI calls login and logout — see [`nasiko auth`](https://docs.nasiko.com/reference/cli/setup#auth).

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/api/auth/login` | Exchange a username and password for a session token |
| `POST` | `/api/auth/logout` | Revoke the current session token |
| `POST` | `/api/auth/change-password` | Change your own password and get a fresh token |
| `GET` | `/api/me` | Identity of the caller |
| `GET` | `/api/me/onboarding` | First-run state and chosen persona |
| `PATCH` | `/api/me/onboarding` | Save a persona and mark the starting guide complete |
| `GET` | `/api/settings` | Workspace settings, plus the values the server runs with |
| `PUT` | `/api/settings` | Replace the editable workspace settings |
| `GET` | `/api/settings/composio` | Composio key status and toolkit selection |
| `PUT` | `/api/settings/composio` | Set the Composio key and switch toolkits on or off |
| `POST` | `/api/assessments` | Submit the free TokenOps assessment form |

## Authentication

Every endpoint on this page except `POST /api/auth/login` needs a session. Send the token from login as `Authorization: Bearer <token>`, or rely on the `access_token` cookie the dashboard holds.

When the session is missing, expired, or revoked, the server answers `401`:

```json theme={null}
{ "data": null, "status_code": 401, "message": "missing or invalid token" }
```

A cookie-authenticated write (`POST`, `PUT`, `PATCH`, `DELETE`) sent from an origin that isn't in the server's allowed origins is refused with `403` and `"message": "cross-origin request refused"`. Bearer-token calls aren't affected.

**Request bodies.** Send `Content-Type: application/json`. A body that isn't valid JSON, or that is missing a required field or has a wrong type, is rejected before the handler runs, with a `400`, `415`, or `422` and a plain-text description.

**Rate limits.** Where a limit applies, the server answers `429` with the plain-text body `rate limit exceeded, try again shortly` and a `Retry-After` header in seconds. Limits are listed on each endpoint.

**Error bodies.** Handler errors on this page are JSON with an `error` message and, where noted, a machine-readable `code`. A few return a plain-text body instead; each endpoint's **Errors** table says which.

> [!NOTE]
>
> **Plans:** Free, Individual, Pro, and Enterprise. **Self-hosted:** Enterprise license.

This label covers the role hierarchy. "Admin role" below applies on Nasiko Cloud and on a self-hosted Enterprise server, where it means the `admin` role or a superuser. A self-hosted open-source server has no role hierarchy: every signed-in user passes role checks. Superuser is a separate flag everywhere. See [access control](https://docs.nasiko.com/governance/access-control/overview.md).

## Sign in

`POST /api/auth/login`

Exchanges a username and password for a session token. Use it to get the bearer token for every other call in the API. The dashboard's login screen calls it, and so does `nasiko auth login` when it signs in with a username and password.

**Auth:** none.

**Rate limit:** 30 requests per minute, counted across all callers of this endpoint on the server.

### Request body

Send either a username and password, or an access key and access secret. An access key pair is what an administrator gets when they create a user — the secret is that user's password.

| Field | Type | Required | Description |
| - | - | - | - |
| `username` | string | With `password` | Username. An access key is also accepted here |
| `password` | string | With `username` | Password |
| `access_key` | string | With `access_secret` | Access key, instead of `username` |
| `access_secret` | string | With `access_key` | Access secret, instead of `password` |

### Example

```bash theme={null}
curl -X POST https://<your-host>/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "username": "ada", "password": "correct-Horse-battery-1" }'
```

```json theme={null}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user_id": "3f6c1a52-8e0e-4d4b-9a51-7c2b1d0e9f11",
  "username": "ada",
  "is_superuser": false,
  "expires_in": 604800
}
```

The response also sets an `access_token` cookie (`HttpOnly`, `SameSite=Strict`, `Path=/`, and `Secure` when the request arrived over HTTPS) with the same token, so a browser session works without the header.

### Errors

| Status | Body | When |
| - | - | - |
| `401` | `{ "error": "invalid credentials" }`, sometimes with `remaining_attempts` | Wrong username or password |
| `401` | `{ "error": "account disabled" }` | The account is deactivated |
| `429` | `{ "error": "...", "code": "account_locked", "retry_after_secs": 900 }` | Too many failed attempts on this account |
| `429` | Plain text, `Retry-After` header | The endpoint's rate limit was hit |
| `500` | `{ "error": "internal error" }` | Server-side failure |

### Behavior

* **Token lifetime.** A session token is valid for 7 days (`expires_in` is in seconds). Sign in again when it expires; there is no refresh endpoint.
* **Lockout.** Three consecutive wrong passwords lock the account for 15 minutes. The third failure already returns `429` with `account_locked`. Until then, a failure may include `remaining_attempts`. A successful sign-in resets the count.
* Each successful sign-in issues a new, independent token. Earlier tokens stay valid until they expire or you sign out.

## Sign out

`POST /api/auth/logout`

Revokes the token you call it with and clears the browser cookie. Use it when a user signs out, or to retire a token you no longer need. `nasiko auth logout` calls it before clearing its local token.

**Auth:** session token. Any signed-in user.

No request body.

### Example

```bash theme={null}
curl -X POST https://<your-host>/api/auth/logout \
  -H "Authorization: Bearer $TOKEN"
```

Returns `204 No Content` with a `Set-Cookie` header that expires the `access_token` cookie.

### Errors

| Status | Body | When |
| - | - | - |
| `401` | `{ "data": null, "status_code": 401, "message": "..." }` | The token is already invalid, expired, or revoked |

### Behavior

* Only the presented token is revoked. Other sessions for the same user — another browser, the CLI — stay signed in. To sign out everywhere, change your password.
* Calling it again with the same token returns `401`, because that token is now revoked.

## Change password

`POST /api/auth/change-password`

Changes the caller's own password. Use it from a settings screen or script when a user rotates their password. In the dashboard: **Account → Password**.

**Auth:** session token. Any signed-in user, for their own account only.

**Rate limit:** 10 requests per minute per user.

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `current_password` | string | Yes | The password the user signs in with now |
| `new_password` | string | Yes | The new password. Must differ from `current_password` and meet the policy below |

**Password policy.** 12 to 64 characters and at most 72 bytes, with at least one lowercase letter, one uppercase letter, one digit, and one symbol (any character that isn't a letter or digit, including a space). Letter and digit checks are Unicode-aware.

### Example

```bash theme={null}
curl -X POST https://<your-host>/api/auth/change-password \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "current_password": "correct-Horse-battery-1", "new_password": "Staple-Orbit-42-lantern" }'
```

```json theme={null}
{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 604800
  }
}
```

The response also sets the `access_token` cookie to the new token.

### Errors

All JSON errors have the shape `{ "error": "<message>", "code": "<code>" }`.

| Status | `code` | When |
| - | - | - |
| `400` | `password_too_short`, `password_too_long`, `password_too_many_bytes`, `password_missing_lowercase`, `password_missing_uppercase`, `password_missing_digit`, `password_missing_symbol` | `new_password` fails the policy. Checked before the current password |
| `400` | `password_unchanged` | `new_password` equals `current_password` |
| `403` | `current_password_incorrect` | `current_password` is wrong |
| `409` | `no_local_password` | The account signs in through an identity provider and has no local password |
| `429` | — (plain text, `Retry-After`) | More than 10 attempts in a minute |
| `500` | `internal_error` | Server-side failure |

### Behavior

* **Every session is signed out.** On success, all of the user's existing tokens are revoked — other browsers, the CLI, and the token used for this call. Replace your stored token with the one in the response. The CLI needs `nasiko auth login` again.
* If the password changes but a fresh token can't be issued, the server returns `204 No Content` and clears the cookie. The new password is in effect; sign in again with it.

## Get the current identity

`GET /api/me`

Returns who the token belongs to. Use it to check a token is still valid, or to read the caller's user ID and superuser flag.

**Auth:** session token. Any signed-in user.

### Example

```bash theme={null}
curl https://<your-host>/api/me \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "sub": "3f6c1a52-8e0e-4d4b-9a51-7c2b1d0e9f11",
  "username": "ada",
  "is_superuser": false
}
```

| Field | Type | Description |
| - | - | - |
| `sub` | string (UUID) | The user's ID |
| `username` | string | Username |
| `is_superuser` | boolean | Whether the user holds the superuser flag |

The response carries only what's in the token. For the full profile (email, role, placement), `nasiko auth whoami` reads `GET /api/users/me`.

### Errors

| Status | Body | When |
| - | - | - |
| `401` | `{ "data": null, "status_code": 401, "message": "..." }` | Missing, expired, or revoked token |

## Get onboarding state

`GET /api/me/onboarding`

Tells you whether the caller has finished the dashboard's **Starting guide**, and which persona they picked. The dashboard reads it on load to decide whether to open the guide.

**Auth:** session token. Any signed-in user, for their own account.

### Example

```bash theme={null}
curl https://<your-host>/api/me/onboarding \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "is_first_time_user": true,
  "persona": null
}
```

| Field | Type | Description |
| - | - | - |
| `is_first_time_user` | boolean | `true` until the user saves a persona for the first time |
| `persona` | string or null | The saved persona, or `null`. Values are listed under [Save a persona](#save-a-persona) |

### Errors

| Status | Body | When |
| - | - | - |
| `401` | Plain text `invalid user identity`, or the JSON auth error | Missing or invalid token |
| `404` | Plain text `user not found` | The account no longer exists |
| `500` | Plain text `internal error` | Server-side failure |

## Save a persona

`PATCH /api/me/onboarding`

Saves the caller's persona and marks onboarding complete. The dashboard calls it when the user finishes the **Starting guide**.

**Auth:** session token. Any signed-in user, for their own account.

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `persona` | string | Yes | One of `developer`, `platform_engineer`, `finance`, `engineering_manager`, `product_manager`, `data_analyst`, `support_lead`, `sre`, `leadership` |

### Example

```bash theme={null}
curl -X PATCH https://<your-host>/api/me/onboarding \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "persona": "platform_engineer" }'
```

```json theme={null}
{
  "is_first_time_user": false,
  "persona": "platform_engineer"
}
```

### Errors

Same as [Get onboarding state](#get-onboarding-state). An unknown `persona` value is rejected with `422` before the handler runs.

### Behavior

* The completion time is recorded the first time only. Later calls change the persona but keep the user marked as onboarded.
* Safe to repeat with the same value.

## Get workspace settings

`GET /api/settings`

Returns the workspace-wide settings, plus the models and flow limits the server is running with. In the dashboard: **Settings → General**, **Flow limits**, and **Registry**.

**Auth:** session token. Any signed-in user.

### Example

```bash theme={null}
curl https://<your-host>/api/settings \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "registry_url": "https://registry.example.com",
  "catalog_tabs": "devops, finance, support",
  "default_embedding_provider": "openai",
  "default_embedding_model": "text-embedding-3-small",
  "default_embedding_api_key_configured": true,
  "orchestrator_model": "gpt-4o",
  "router_model": "gpt-4o-mini",
  "default_provider": "openai",
  "max_flow_depth": 5,
  "max_flow_fan_out": 20,
  "max_flow_tokens": 100000,
  "flow_timeout_secs": 600
}
```

**Editable fields** (change them with `PUT /api/settings`):

| Field | Type | Description |
| - | - | - |
| `registry_url` | string or null | Extra OCI registry that registry imports accept, besides the built-in ones. Only the host is used |
| `catalog_tabs` | string or null | Comma-separated agent tags pinned as the agent catalog's filter tabs. Empty derives tabs from the most common tags |
| `default_embedding_provider` | string or null | Workspace default provider for embeddings |
| `default_embedding_model` | string or null | Workspace default embedding model |
| `default_embedding_api_key_configured` | boolean | Whether a default embedding API key is stored. The key itself is never returned |

**Read-only fields** come from the server's environment and change only on restart:

| Field | Environment variable | Description |
| - | - | - |
| `orchestrator_model` | `OPENAI_MODEL`, else `DEFAULT_MODEL` | Model the orchestrator uses |
| `router_model` | `ROUTER_MODEL`, else `DEFAULT_MODEL` | Model the [routing engine](https://docs.nasiko.com/build/routing-engine.md) uses to pick which agent answers |
| `default_provider` | `DEFAULT_PROVIDER` | Default provider for the LLM router |
| `max_flow_depth` | `NASIKO_FLOW_MAX_DEPTH` | Max call depth per flow |
| `max_flow_fan_out` | `NASIKO_FLOW_MAX_FAN_OUT` | Max total agent invocations per flow |
| `max_flow_tokens` | `NASIKO_FLOW_MAX_TOKENS` | Token budget per flow |
| `flow_timeout_secs` | `NASIKO_FLOW_TIMEOUT_SECS` | Wall-clock timeout per flow |

See [flow limits](https://docs.nasiko.com/governance/flow-limits.md) for what these limits enforce.

A workspace that has never saved settings returns `null` for every editable field.

### Errors

| Status | Body | When |
| - | - | - |
| `401` | JSON auth error | Missing or invalid token |
| `500` | Plain text `internal error` | Server-side failure |

## Update workspace settings

`PUT /api/settings`

Replaces the editable workspace settings. Use it to set the registry URL, catalog tabs, or the default embedding model.

**Auth:** session token. **Role:** admin role or superuser. This check applies on a self-hosted open-source server too.

### Request body

> [!WARNING]
>
> `PUT` replaces the whole record. A field you leave out is saved as `null`. Read the current values with `GET /api/settings` first and send all of them back with your change. The embedding API key is the exception — see `default_embedding_api_key`.

| Field | Type | Required | Description |
| - | - | - | - |
| `registry_url` | string or null | No | Extra OCI registry host for registry imports |
| `catalog_tabs` | string or null | No | Comma-separated agent tags for the catalog's filter tabs |
| `default_embedding_provider` | string or null | No | Must be a provider the server knows. Set together with `default_embedding_model`, or leave both out |
| `default_embedding_model` | string or null | No | Set together with `default_embedding_provider` |
| `default_embedding_api_key` | string | No | New default embedding API key, stored encrypted. Omitted or blank keeps the stored key |
| `clear_default_embedding_api_key` | boolean | No | `true` removes the stored key. Default `false` |
| `confirm_embedding_change` | boolean | No | `true` confirms a change to an already-set embedding provider or model. Default `false` |

### Example

```bash theme={null}
curl -X PUT https://<your-host>/api/settings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "registry_url": "https://registry.example.com",
    "catalog_tabs": "devops, finance, support",
    "default_embedding_provider": "openai",
    "default_embedding_model": "text-embedding-3-small"
  }'
```

Returns the same object as `GET /api/settings`, with the saved values.

### Errors

| Status | Body | When |
| - | - | - |
| `400` | `{ "error": "...", "code": "invalid_embedding_default" }` | Only one of provider and model is set, or the provider isn't known |
| `403` | `{ "error": "requires admin role" }` | Caller has neither the admin role nor the superuser flag |
| `428` | `{ "error": "...", "code": "embedding_change_requires_confirmation", "details": { "from": {...}, "to": {...} } }` | The embedding provider or model is already set and this request changes or clears it without `confirm_embedding_change: true` |
| `500` | Plain text `internal error` | Server-side failure |

### Behavior

* **Changing the embedding model needs confirmation.** Content already indexed with the old model can't be compared with vectors from the new one, so searches return worse matches until you re-index. The first request returns `428` with `details.from` and `details.to` (each `{ "provider", "model" }`). Re-send with `confirm_embedding_change: true` to proceed. Setting an embedding default for the first time, or re-sending the same one, needs no confirmation.
* Read-only fields in the body are ignored.
* Changes apply without a restart.

## Get Composio settings

`GET /api/settings/composio`

Shows whether a Composio API key is in effect, where it comes from, and which Composio toolkits are switched on for the MCP gateway. In the dashboard: **Settings → MCP toolkits**.

**Auth:** session token. **Role:** superuser.

### Example

```bash theme={null}
curl https://<your-host>/api/settings/composio \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "api_key_configured": true,
  "key_source": "ui",
  "stored_key_unreadable": false,
  "toolkits": [
    {
      "toolkit": "github",
      "display_name": "Github",
      "description": "Manage repositories, issues, pull requests, and code search on GitHub.",
      "logo_url": "https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/github.svg",
      "enabled": true
    },
    {
      "toolkit": "slack",
      "display_name": "Slack",
      "description": "Send messages, read channels, and manage threads in Slack.",
      "logo_url": "https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/slack.svg",
      "enabled": false
    }
  ],
  "failed": []
}
```

| Field | Type | Description |
| - | - | - |
| `api_key_configured` | boolean | Whether any Composio key is in effect |
| `key_source` | string | `ui` (saved through this API or the dashboard), `env` (the server's `COMPOSIO_API_KEY`), or `none` |
| `stored_key_unreadable` | boolean | A key was saved but can no longer be decrypted, so the server ignores it and falls back to `COMPOSIO_API_KEY` if set. Save the key again |
| `toolkits` | array | Every toolkit on offer, alphabetically, with `toolkit` (ID), `display_name`, `description`, `logo_url`, and `enabled` |
| `failed` | array | Always empty on `GET`. On `PUT`, toolkits that couldn't be applied, as `{ "toolkit", "error" }` |

The key itself is never returned.

### Errors

| Status | Body | When |
| - | - | - |
| `403` | Plain text `requires superuser` | Caller isn't a superuser |
| `500` | Plain text `internal error` | Server-side failure |

## Update Composio settings

`PUT /api/settings/composio`

Saves or clears the Composio API key and chooses which toolkits are switched on. Every field is optional: what you leave out stays as it is.

**Auth:** session token. **Role:** superuser.

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `api_key` | string | No | New Composio API key, stored encrypted. Blank is ignored |
| `clear_api_key` | boolean | No | `true` removes the saved key. The server then falls back to `COMPOSIO_API_KEY`, if set. Default `false`. Can't be combined with `api_key` |
| `toolkits` | string\[] | No | The complete set of toolkit IDs to have switched on. Toolkits not in the list are switched off. Case-insensitive. `[]` switches all off. Omit to leave the selection unchanged |

### Example

```bash theme={null}
curl -X PUT https://<your-host>/api/settings/composio \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "ak_...", "toolkits": ["github", "slack"] }'
```

Returns the same object as `GET /api/settings/composio`, with `failed` listing any toolkit that couldn't be registered or moved:

```json theme={null}
{
  "api_key_configured": true,
  "key_source": "ui",
  "stored_key_unreadable": false,
  "toolkits": [
    { "toolkit": "github", "display_name": "Github", "description": "...", "logo_url": "...", "enabled": true },
    { "toolkit": "slack", "display_name": "Slack", "description": "...", "logo_url": "...", "enabled": true }
  ],
  "failed": []
}
```

### Errors

| Status | Body | When |
| - | - | - |
| `400` | `{ "error": "send either api_key or clear_api_key, not both", "code": "conflicting_key_update" }` | Both `api_key` and `clear_api_key: true` sent |
| `400` | `{ "error": "unknown toolkit '<name>'", "code": "unknown_toolkit" }` | A toolkit ID isn't on offer |
| `400` | `{ "error": "add a Composio API key before switching toolkits on", "code": "composio_not_configured" }` | Switching toolkits on with no key in effect |
| `403` | Plain text `requires superuser` | Caller isn't a superuser |
| `5xx` | Plain text | Composio or the server failed while applying the selection |

### Behavior

* **The key takes effect at once.** Cached MCP gateway sessions are cleared so the next tool call uses the new key. Other server replicas pick up a saved key within about 15 seconds.
* **Changing to a key from a different Composio project** re-creates each enabled toolkit's auth config under the new project. A toolkit that uses its own OAuth app can't be re-created this way; it appears in `failed` and must be registered again with that app.
* **Switching a toolkit on for the first time** registers it with Composio. A toolkit Composio refuses appears in `failed`; the rest still apply.
* End users still connect their own accounts to each toolkit. See [MCP gateway](https://docs.nasiko.com/build/mcp/overview.md).

## Submit an assessment

`POST /api/assessments`

Submits the dashboard's **Free TokenOps assessment** form: how you run agents today and what you spend. The dashboard shows it at `/assessment`, then offers a booking slot with the Nasiko team.

**Auth:** session token. Any signed-in user.

**Rate limit:** 5 requests per minute per user.

The server forwards the answers, with your user ID, to the intake endpoint set in `ASSESSMENT_INTAKE_URL`. If that variable isn't set, the endpoint returns `503`.

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `applying_as` | string | Yes | `individual` or `team` |
| `name` | string | Yes | Your name. Max 200 characters |
| `email` | string | Yes | Contact email. Must contain `@`. Max 200 characters |
| `company` | string | When `applying_as` is `team` | Company name. Max 200 characters |
| `agents` | string | Yes | How many agents you run (free text, such as `2-5`). Max 200 characters |
| `spend` | string | Yes | Current model spend (free text). Max 200 characters |
| `challenges` | string\[] | No | Up to 20 challenges, each max 200 characters. Default `[]` |
| `notes` | string | No | Free-form notes. Max 5,000 characters. Default `""` |

### Example

```bash theme={null}
curl -X POST https://<your-host>/api/assessments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applying_as": "team",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "company": "Acme",
    "agents": "6-20",
    "spend": "$5k-$20k / month",
    "challenges": ["Cost visibility", "Model choice"],
    "notes": "Mostly Claude Code and Codex."
  }'
```

`201 Created`:

```json theme={null}
{
  "data": { "id": "<receipt-id>" }
}
```

`id` is the receipt ID the intake endpoint returned.

### Errors

All JSON errors have the shape `{ "error": "<message>", "code": "<code>" }`.

| Status | `code` | When |
| - | - | - |
| `400` | `invalid_assessment` | A required answer is missing or blank, the email has no `@`, a team has no company, or an answer is too long |
| `429` | — (plain text, `Retry-After`) | More than 5 submissions in a minute |
| `502` | `assessment_store_failed` | The intake endpoint didn't accept the submission |
| `503` | `assessments_not_configured` | `ASSESSMENT_INTAKE_URL` isn't set |

### Behavior

* Not idempotent: each successful call creates a new submission.
* The server waits up to 15 seconds for the intake endpoint before returning `502`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.