Authorization

Salsa requires an OAuth 2.0 Bearer Token in the Authorization header of all requests made to our APIs. Salsa supports the following ways to obtain one, each described in detail below:

Both the API Token and OAuth Client Credentials are machine-to-machine authorization: no user signs in. The difference is what you hand out:

• An API Token is a static, long-lived token. Whoever holds it has access until Salsa revokes it, so it should only ever be used by your own backend.
• OAuth Client Credentials use the standard OAuth 2.0 client credentials flow. Your backend keeps the client secret and mints a short-lived access token from it, so a platform you pass the token to never holds a long-lived credential. Use them instead of an API Token whenever a token leaves your backend, for example when you connect an external agent platform or MCP client to Salsa on your behalf.

API Token

Salsa provides two API Tokens that are used to access our APIs. One for the Sandbox environment and one for Production environment. These tokens grant many privileges, so it's important to keep them secure and never use or share them publicly.

Use the following base URLs when making requests to Salsa API

• Sandbox: api.sandbox.salsa.dev
• Production: api.salsa.dev

OAuth Client Credentials

OAuth Client Credentials are machine-to-machine authorization, like the API Token, but they follow the standard OAuth 2.0 client credentials flow, so you don't have to hand out a long-lived token. Your backend exchanges a client ID and client secret for a short-lived access token, and uses that token, or passes it to the platform acting for you, until it expires.

Salsa provisions the OAuth client for your partner account and shares its client ID and client secret with you. The client's access is set by Salsa when it is provisioned, and is typically the same as your API Token's.

Minting an access token

Request a token from https://api.stytch.salsa.dev/v1/oauth2/token using the OAuth 2.0 client credentials grant. The same token URL is used for sandbox and production:

curl --request POST \
     --url https://api.stytch.salsa.dev/v1/oauth2/token \
     --header 'content-type: application/json' \
     --data '{
          "grant_type": "client_credentials",
          "client_id": "${SALSA_CLIENT_ID}",
          "client_secret": "${SALSA_CLIENT_SECRET}"
        }'

The response contains the access token and how many seconds it is valid for:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600
}

Use the access token as a Bearer Token, exactly as you would an API Token:

curl --request GET \
     --url https://api.sandbox.salsa.dev/api/rest/v1/employers/${SALSA_EMPLOYER_ID} \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ${ACCESS_TOKEN}'

An access token minted this way can also create User Tokens for your users.

Keeping your session alive

Access tokens are valid for 1 hour and there is no refresh token. To keep a long-running integration or agent authenticated, your backend should request a new access token shortly before the current one expires (using expires_in). Reuse a token for its whole lifetime rather than requesting a new one for every API call.

Keeping your credentials secure

• Keep the client secret on your servers. Never ship it to a browser or mobile app, or share it publicly.
• An issued access token can't be revoked on its own. If your client secret may have been exposed, contact us so we can disable the client or rotate its secret. New tokens can't be minted after that, and tokens already issued stop working when they expire, within at most an hour.

User Token

A User Token allows you to temporarily provision access for a user. By assigning an access role during creation, you can specify their level of access to your data.

To create a User Token, send a request to Salsa’s Credentials API, authenticated with your API Token or an access token minted with OAuth Client Credentials. This is an example of how to create a User Token with the EMPLOYER_ADMIN access role in the sandbox environment:

curl --request POST \
     --url https://api.sandbox.salsa.dev/api/rest/v1/auth/token \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ${YOUR_SANDBOX_API_TOKEN}' \
     --header 'content-type: application/json' \
     --data '{
          "type": "CreateEmployerUserTokenInput",
          "role": "EMPLOYER_ADMIN",
          "employerIds": [
            "${SALSA_EMPLOYER_ID_1}",
            "${SALSA_EMPLOYER_ID_2}"
          ]
        }'

The token generated in the example is valid for 1 hour, after which, a new token needs to be issued. The expiration time is configurable.

See Create User API token API reference for more details.

Available Roles

There are three tiers of roles: basic, admin, and super-admin. Each tier grants the permissions of the tier below it, plus more. Every tier also have *_ONBOARDING_* variants with reduced permissions only necessary for onboarding workflows of the UI Experiences.

Users may be enabled to step up to higher role/tier, see Protecting sensitive actions with identity verification .

Sensitive and privileged actions

Sensitive actions are gated by tier. Adding a bank account or editing a worker's government ID value requires admin. Unmasking a full bank account number or government ID (SSN/TIN), removing a worker bank account, and downloading the Worker Details report with government IDs require super-admin. Basic roles can do none of these.

A worker's government ID requirement — whether the ID is MANDATORY or still APPLIED_FOR — is ordinary worker data, not sensitive, and can be set by any role that can edit the worker.

These limits are enforced at the API, not just in the UI. To grant a higher-tier action on demand instead of issuing the higher role up front, use the step-up flow in Protecting sensitive actions with identity verification, which lists the full action-to-role matrix.

Deprecated roles

The following roles still work but are considered deprecated. If you're still using them consider replacing them with the corresponding roles:

User Sessions

People who sign in to Salsa directly, such as your team using the Salsa dashboard, or an AI assistant connected to Salsa on a user's behalf, authenticate through an interactive OAuth 2.0 sign-in rather than a token you create.

A signed-in session issues a short-lived access token together with a refresh token. The client uses the refresh token to get new access tokens automatically, so the user stays signed in without re-authorizing every hour, for as long as their session remains valid. Signing out, or the session expiring, ends access.

For unattended or long-running access that shouldn't depend on a person's session, such as scheduled jobs or agents, use OAuth Client Credentials instead.