/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 exceptPOST /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:
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.
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
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_inis 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
429withaccount_locked. Until then, a failure may includeremaining_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
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
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 loginagain. - If the password changes but a fresh token can’t be issued, the server returns
204 No Contentand 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 unknownpersona 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
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
Example
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
428withdetails.fromanddetails.to(each{ "provider", "model" }). Re-send withconfirm_embedding_change: trueto 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
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
failedand 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.