Docs/Authentication

Authentication

Ptolemy uses long-lived robot tokens for API access. Robot users are service accounts designed for machine-to-machine integration — they authenticate on every request via a Bearer token and don't require a login flow.

How it works

Every API request must include a valid robot token in the Authorization header. There is no session, no cookie, and no refresh flow — the token is the only credential.

Request header

Authorization: Bearer ptk_live_a3f9b2c1d4e5...

If the token is missing, expired, or revoked, the API returns 401 Unauthorized. If the token is valid but the robot user’s role lacks permission for the operation, the API returns 403 Forbidden.

Robot users

A robot user is a service account tied to a single workspace. Robot users are created by a workspace Admin, either through the dashboard (Workspace Settings → API Tokens) or via the API.

Each robot user has a display_name, an optional description, and a role that determines what operations it can perform.

Robot users are locked to their workspace and cannot access other workspaces. Deleting a robot user’s membership also deletes the underlying user record and revokes all tokens.

POST/memberships/robotsCreate a robot userAdmin▶

GET/memberships/robotsList robot usersAdmin▶

GET/memberships/robots/{userId}Get a robot userAdmin▶

PATCH/memberships/{membershipId}Update membership roleAdmin▶

DELETE/memberships/{membershipId}Remove a memberAdmin▶

Roles & permissions

Robot users are restricted to two roles. The Editor and Admin roles are reserved for human users.

Role	Read data	Create & update	Archive & delete	Manage members & settings
Viewer	✓	—	—	—
Member	✓	✓	✓	—

Use Viewer for read-only integrations like dashboards or reporting tools. Use Member for integrations that need to create or modify data.

Token management

A robot user can have multiple tokens, allowing you to rotate credentials without downtime. Tokens have a ptk_live_ prefix and are 64 characters of hex after the prefix.

The raw token value is returned once at creation time and can never be retrieved again. Store it securely immediately. Only the last 4 characters are stored as token_suffix for identification in the dashboard and API responses.

POST/memberships/robots/{userId}/tokensCreate a tokenAdmin▶

GET/memberships/robots/{userId}/tokensList tokensAdmin▶

DELETE/memberships/robots/{userId}/tokens/{tokenId}Revoke a tokenAdmin▶

Token lifecycle

Tokens can be in one of three states:

Active

The token is valid and accepts requests. This is the default state after creation.

Expired

The token’s expires_at date has passed. Requests return 401. Create a new token to restore access.

Revoked

The token was explicitly revoked. This is permanent and cannot be undone.

Token	Lifetime	Transport	Storage
Robot API Token	Optional expiry (ISO 8601)	`Authorization: Bearer`	Hashed in robot_tokens table. Last 4 chars stored as token_suffix.
Access Token (JWT)	15 minutes	`Authorization: Bearer`	Client memory (human users only)
Refresh Token	7 days (sliding)	HttpOnly cookie	Hashed in refresh_tokens table (human users only)

Error responses

Authentication-related errors:

Status	Scenario	Common causes
401	Unauthorized	Missing Authorization header, malformed token, expired token, revoked token, deleted robot user
403	Forbidden	Valid token but insufficient role — e.g. a Viewer attempting a write

401 — Expired token

{
  "status": 401,
  "error": "unauthorized",
  "message": "Token has expired. Create a new token for this robot user."
}

403 — Insufficient role

{
  "status": 403,
  "error": "forbidden",
  "message": "This operation requires the Member role or above."
}