Skip to main content
The sajn API authenticates every request with a bearer token in the Authorization header. For a server that works with your own sajn organization, that token is an API key, which this page covers. If you build software that other sajn customers connect to their own accounts, use OAuth 2.0 instead. If you’re not sure which applies to you, see Choosing an authentication method.

Create an API key

To create a key, you must be an administrator in every workspace the key can act in, or own the organization, and the organization needs API access. API access is included from the Team plan, and in every sandbox.
  1. In the sajn app, go to Inställningar > Utvecklare > API-nycklar.
  2. Click Skapa nyckel.
  3. In Namn, enter a name that says what uses the key, such as crm-sync-production.
  4. In Arbetsytor, select the workspaces that the key can act in. If you select more than one, choose the Standardarbetsyta that requests act in when they don’t name a workspace.
  5. In Behörigheter, select Alla, Endast läsning, or Anpassade, and adjust the permissions. The key has the same permissions in every workspace it can act in.
  6. In Utgår, choose when the key expires: after 30 days, 90 days, 1 year, or never.
  7. Click Skapa nyckel, and copy the key. sajn shows the full key only once.
sajn emails the workspace members who can manage API keys when a key is created. Before a key expires, sajn emails the person who created it and the administrators of its default workspace, 14 days before and the day before.

Key prefixes

The prefix tells you which environment a key belongs to, and whether a service account or a person owns it: Every sandbox key contains _dev_. After the prefix come 46 characters: 40 random characters and a 6-character checksum. Older keys start with sajn_sk_, sajn_dev_, or api_, and they keep working. Production and sandbox keys use the same base URL. The key decides which environment the request reaches.

Send the key

Send the key as a bearer token in the Authorization header, together with the API version:
These samples read the key from the SAJN_API_KEY environment variable.

What a key can do

Every API key runs as its own service account, a non-human account that the organization owns. The key doesn’t depend on the person who created it, so it keeps working when that person changes role or leaves the organization.
  • Its workspaces. The key can act in the workspaces you selected, and each request acts in one of them. For more information, see Choose a workspace.
  • Its permissions. The key can do what its permissions allow, in every workspace it can act in, and nothing more. A key can’t administer a workspace. A request that the permissions don’t allow fails with the code PERMISSION_DENIED.
  • No scopes. Unlike an OAuth token, an API key isn’t limited to a set of scopes.
To change a key’s name, workspaces, or permissions, click Redigera in the key’s menu in the API key list. If the organization is suspended, requests with the key fail with the code ACCOUNT_INACTIVE. To check which account, workspace, and organization a request acts as, call GET /me:
The response is similar to the following. email and name belong to the key’s service account:

Choose a workspace

A request without a Sajn-Workspace header acts in the key’s default workspace. To act in another workspace that the key can act in, send the workspace’s ID in the Sajn-Workspace header:
Replace WORKSPACE_ID with the id of the workspace. To list the workspaces the key can act in, call GET /workspaces. The workspace that the request acts in has isCurrent set to true. The header follows these rules:
  • It takes a workspace ID, not a slug, so renaming a workspace doesn’t break your integration.
  • A workspace that doesn’t exist, or that the key can’t act in, returns 403 WORKSPACE_ACCESS_DENIED. sajn never falls back to the default workspace.
  • A value that isn’t a single workspace ID returns 400 VALIDATION_FAILED.
  • If the key’s default workspace was deleted, a request without the header returns 400 WORKSPACE_REQUIRED. To fix it, edit the key and save it with a new default workspace, or send the header.
  • It works in every API version and on the MCP server.
Idempotency keys, webhooks created through the API, and the isCurrent flag all follow the workspace that the request acts in. The rate limit is per organization, so it doesn’t change with the workspace.

Rotate a key

To replace a key without downtime, do the following:
  1. Create a new key, as described in Create an API key.
  2. Deploy the new key to your integration.
  3. Confirm in the Senast använd column of the API key list that the old key is no longer used.
  4. In the old key’s menu, click Återkalla.
You can also regenerate a key from its menu. Regenerating replaces the secret at once: the old value stops working immediately. The key keeps its name, workspaces, and permissions, and you choose when the new secret expires. You can’t extend a key’s expiration date, so to renew a key that’s about to expire, regenerate it. Regenerate a key at once when it has leaked and must stop working now.

Keep keys safe

Store keys in environment variables or a secrets manager. Never commit a key to version control, and never send it to a browser or a mobile app.
A separate key for each integration and environment, with only the workspaces and permissions it needs, limits what a leaked key exposes, and lets you revoke one without breaking the others. Use a sandbox key for development and testing.
A key that expires limits how long a leaked key works. Regenerate it before it expires.
The API key list shows when each key was last used. Revoke keys you no longer use. To see individual requests, open the API-loggar tab in Konsol.

Authentication errors

A failed authentication returns an error in the standard shape. Branch on code, not on message, show userMessage to your users, and log requestId:
The following codes relate to authentication: In API version 2026-09, the error body has no requestId, and the code values differ. For every error code, see Errors. For the request limits per organization, see Rate limits.