Authentication

Every API call carries a bearer token in the Authorization header. There are two kinds.

	API key	Session token
Looks like	nk_…	a short-lived signed token
Who it acts as	a service principal in one workspace	a person in one workspace
Lifetime	until revoked or its expiry date	15 minutes, renewed by the browser session
Use it for	servers, integrations, scripts	the NeodyAI web app (and apps embedded in it)
Created in	Settings → API keys	signing in

GET /v1/me HTTP/1.1
Host: app.neody.ai
Authorization: Bearer nk_…

One workspace per token

A token belongs to exactly one workspace. Every record you read or write is in that workspace; data from other workspaces is invisible to it, enforced in the database itself (see Workspaces & data isolation). To work with several workspaces, use one key per workspace.

What a token may do

A token holds roles, and roles grant permissions. Endpoints check permissions, never roles — so the Permissions page is the contract.

• An API key is created with one or more roles (viewer, member, process_owner, finance, approver) and, optionally, a list of apps. A key limited to apps can only call those apps' endpoints.
• A person's session carries the roles they hold in the workspace; suspending someone takes effect on their next request.

Agents act for a person, never beyond them

AI agents run as their own principal, on behalf of a person. Their permissions are the agent role's, capped at the permissions of the person they act for — an agent acting for a viewer can't write anything. Every agent action is recorded with both identities.

Keys and safety

• Keep keys on servers. Never put a key in a browser, a mobile app or a URL.
• Give each integration its own key with the smallest role it needs, and an expiry.
• Revoke a key in Settings → API keys; the next call with it is refused.
• Key creation, activation and revocation are written to the workspace's tamper-evident audit log.

Errors

Status	Meaning
401	No token, an expired session, or a revoked/unknown key
403	The token is valid but lacks the permission. The message names it, e.g. "You don't have permission to do this (Create and change records)."

See Errors & limits for the rest.