Skip to main content
sajn has separate authentication methods for separate problems. They aren’t interchangeable, and switching later means rebuilding, so pick one before you write code. The deciding question is whose sajn account your integration works with.

Pick by what you build

Your own backend, your own sajn account

A server you control that sends or reads documents in your own organization.Use an API key. No browser step, no token lifecycle, no refresh logic.

Software other organizations install

A product, marketplace app, or integration that connects to many sajn customers’ accounts.Use OAuth 2.0. Each customer grants access to their own account and can revoke it.

Logging your users in with BankID

People sign in to your application with Swedish BankID.Use sajn Login. It’s a separate product, and it doesn’t grant access to the document API.

Connecting an AI assistant

Claude, Cursor, or VS Code working with a workspace.Use the sajn MCP server. The assistant handles consent and token refresh.

Build a server integration

If your server works with your own organization’s sajn account, for example to send agreements, sync signed documents, or react to webhooks, use an API key. It’s a single static credential in the Authorization header, with nothing to refresh and no step that needs a person in a browser.
OAuth isn’t more secure in this case. It gives the same access with more moving parts. The authorization_code flow exists so that a person can grant a third party access to their account without sharing a password. When your server and the sajn account belong to the same company, there’s no third party.
sajn doesn’t support the client_credentials grant. For server-to-server access, use an API key. To create one, see Authentication.

Workspaces

An API key can act in one or several workspaces of the organization. A request acts in the key’s default workspace, or in the workspace you name in the Sajn-Workspace header. Give each key only the workspaces and permissions its integration needs, so a leaked key exposes no more than that. For more information, see Choose a workspace. Before you write data, confirm which workspace a request acts in with GET /me:
The response is similar to the following:

Build software for many sajn customers

If other organizations install what you build, such as a CRM integration, a marketplace app, or an add-in, use OAuth 2.0. Each customer authorizes your app for their own account, in their own browser, once. They can revoke your access at any time, and you never hold their credentials. sajn supports the authorization_code and refresh_token grants. Access tokens are short-lived, and refresh tokens rotate on every use: the refresh token in a refresh response replaces the one you sent. Store the new refresh token before you do anything else with the response. If you lose it, the customer must authorize your app again. For the requests, scopes, and token lifetimes, see OAuth 2.0.
Don’t ask customers for their API keys. A customer who hands you a key gives you a credential they manage on your behalf: they choose its workspaces and permissions, they must notice when it expires, and they can revoke you only by finding and revoking the right key. OAuth exists for this case.

Methods that aren’t the document API

sajn Login authenticates your own users with BankID and returns claims about who they are. It’s standard OpenID Connect with mandatory PKCE. It issues no refresh tokens, and its tokens don’t grant access to documents, templates, or contacts. For more information, see sajn Login. The sajn MCP server lets AI assistants work with a workspace. Its OAuth flow is built for interactive assistant clients that handle browser consent and token refresh, not for a backend service. For more information, see Workspace MCP.

Summary

Authentication

Create an API key and make your first authenticated request.

OAuth 2.0

Authorize, exchange, and refresh tokens for a multi-customer app.