Authentication

The public API authenticates requests with Workspace API keys using the standard Bearer scheme:

Authorization: Bearer YOUR_API_KEY

curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.limitry.com/v1/workspace

A successful response identifies the workspace the key belongs to:

{ "id": "…", "name": "Example Workspace" }

API keys belong to a workspace

Keys authenticate a workspace, not a person. A key keeps working even if the person who created it leaves the workspace, and it never carries a user session — it cannot be used to sign in.

Creating a key

Workspace owners can create keys in the application under Settings → API Keys:

1. Choose a descriptive name (for example production-backend).
2. Choose what the key may do (see Scopes) — Read only by default.
3. Copy the secret when it is shown — it is displayed exactly once and cannot be viewed again. Store it in your secret manager.
4. The key list shows only safe metadata (name, first characters, access, creation and last-used times).

If a secret is lost, create a replacement key and revoke the old one.

Revoking and rotating

Owners can revoke a key at any time from Settings → API Keys. Revocation is immediate and permanent: the same secret will fail authentication on the next request.

To rotate a key without downtime:

1. Create a replacement key.
2. Update your integration to use it.
3. Revoke the old key.

Scopes

Every key and token is granted scopes when it is created, and can do only what it was granted. A scope names a group of endpoints and whether it may read or change them — for example workspace.audit:read (read the audit trail), workspace.members:read (read members and pending invitations) or workspace:read (read the workspace profile). Each endpoint in the API reference states the scope it needs.

When you create a credential you choose one of:

• Read only (the default) — every read scope available at creation. A scope added to the API later is not granted automatically.
• Full access — everything, including scopes added later.
• Custom — exactly the scopes you tick.

Grant only what an integration needs. A request for an endpoint the credential was not granted is a 403 with code forbidden:

{
  "error": {
    "code": "forbidden",
    "message": "This credential is not granted the workspace.audit:read scope",
    "requestId": "…"
  }
}

To change what an integration may do, create a new credential with the access it needs and revoke the old one.

Personal access tokens

A second credential type exists for acting as yourself rather than as a workspace — for scripts, CI jobs and the command line: personal access tokens (pat_…), created in the application under Account → API tokens — or by the command line itself: login opens your browser, you approve it, and the token for that computer is created and stored for you. A personal access token:

• acts as you, in the workspaces you choose at creation (all of yours, or specific ones), with the scopes you grant it;
• is subject to your workspace role as well: GET /v1/workspace/audit-events is owner-only, like the audit page in the application (a workspace API key is the workspace and has no role);
• expires on the schedule you pick (30 days, 90 days, a year, or never);
• answers the identity check on /v1/user/me:

curl \
  -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
  https://api.limitry.com/v1/user/me

{
  "id": "…",
  "name": "Casey Customer",
  "email": "casey@example.com",
  "workspaces": [
    { "id": "…", "name": "Example", "slug": "example", "role": "owner" }
  ]
}

On every other endpoint a personal access token must say which workspace it acts in, with the X-Workspace header (the workspace slug); the call then runs with your membership in that workspace and the token’s scopes:

curl \
  -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
  -H "X-Workspace: example" \
  https://api.limitry.com/v1/workspace

A missing X-Workspace is a 400; a workspace you are not a member of, or one the token was not scoped to, is a 403 — as is a scope the token was not granted. Workspace API keys ignore the header: a key is its workspace. A workspace API key is never accepted on /v1/user/*. Like API keys, tokens are shown once at creation, revocable from the same page, and stop working immediately if your account is suspended or the token expires.

Apps and AI agents (OAuth)

Apps — including AI agents’ tool connections — can act for a person without ever seeing a key: the product is an OAuth 2.1 authorization server. The app sends the person to sign in, they choose a workspace and approve what the app may do, and the app receives a short-lived access token for the API.

• Discovery: https://api.limitry.com/.well-known/oauth-authorization-server/auth lists every endpoint. Apps may register themselves (dynamic client registration); a registration grants nothing until a person approves.
• An app asks for the same scopes (workspace.audit:read, …), plus offline_access for a refresh token. The person can narrow them.
• A token acts for one person in one workspace — no X-Workspace header — with that person’s role. Request it for the resource https://api.limitry.com/v1.
• The person can disconnect the app at any time under Account → Connected apps; its tokens stop working on the next request.

Authentication failures

Requests with a missing, malformed, invalid, or revoked credential receive a 401 with the standard error envelope:

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "requestId": "…"
  }
}

The response is deliberately identical across failure causes (no enumeration help). Browser session cookies are never accepted on the public API.