API authentication - Devias

A request authenticates in one of two ways: a session cookie or an API key. People sign in through the studio, and the server sets a session cookie. A browser app that calls the API sends that cookie with each request. The studio itself works this way.

API key, for scripts, servers and the CLI

An API key is created in Settings → API keys with an expiry. It is shown once, when it is created. It is sent in the x-api-key header.

curl -X POST "https://api.example.com/api/workspaces/<workspaceId>/records/person/list" \
  -H "x-api-key: $DEVIAS_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "limit": 5 }'

A successful call returns { "items": [...], "nextCursor": ... }. The route GET /api/me requires a signed-in person and does not accept an API key. A key belongs to one workspace and only works there.

Permissions of a key

Each key carries a map from an area to the actions it allows. A call outside that map is refused with FORBIDDEN.

{ "record": ["read", "write"] }

A key made in the studio can read records. A key with more permissions is created through the API with a permissions map. For example, devias plan and devias apply need { "module": ["manage"] }. A key should have only what it needs and should be deleted when no longer used.

Errors: what FORBIDDEN and UNAUTHORIZED look like.
Access and permissions: roles, keys, workflows and agents.