Authorization

Salsa requires an OAuth 2.0 Bearer Token in the Authorization header of all requests made to our APIs. Two token type are supported, which are described in detail below: API Tokens and User Tokens.

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

💡

Having trouble finding your API token?

If you've misplaced your token or need it resent for any reason, contact us.

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. 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.

There are essentially two kinds of roles, admin and basic.

Admin roles

Grants administrative permissions:

• EMPLOYER_ADMIN - View and modify all employer associated data, such as workers, payroll runs, and so on.
• WORKER_ADMIN - View data associated with a specific worker, such as personal information, payment records, and so on.

Same as corresponding employer and worker admin roles, but permissions restricted to onboarding activities. Typically used for some UI experiences.

• WORKER_ONBOARDING_ADMIN
• EMPLOYER_ONBOARDING_ADMIN

Basic roles

Grants basic permissions to not allow to perform sensitive actions, For example can't add a bank account or view/edit worker SSN/TIN:

• EMPLOYER_BASIC
• WORKER_BASIC
• EMPLOYER_ONBOARDING_BASIC
• WORKER_ONBOARDING_BASIC

Deprecated roles

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