Skip to main content
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.

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

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.

Example

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

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

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

Errors

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

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

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

Errors

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

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

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

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

Errors

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

Example

Errors

Same as 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

Editable fields (change them with PUT /api/settings): Read-only fields come from the server’s environment and change only on restart: See flow limits for what these limits enforce. A workspace that has never saved settings returns null for every editable field.

Errors

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

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.

Example

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

Errors

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

The key itself is never returned.

Errors

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

Example

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

Errors

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.

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

Example

201 Created:
id is the receipt ID the intake endpoint returned.

Errors

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

Behavior

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