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.

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 .

Role	Description
`EMPLOYER_BASIC`	Grants basic set of permissions. Cannot perform sensitive actions such as adding bank accounts.
`EMPLOYER_ONBOARDING_BASIC`	Same as `EMPLOYER_BASIC` with only necessary permissions for onboarding workflows.
`WORKER_BASIC`	Grants basic set of permissions. Cannot perform sensitive actions such as adding bank accounts.
`WORKER_ONBOARDING_BASIC`	Same as `WORKER_BASIC` with permissions for onboarding workflows.
`EMPLOYER_ADMIN`	View and modify all employer-associated data, such as workers, payroll runs, and so on.
`EMPLOYER_ONBOARDING_ADMIN`	Same as `EMPLOYER_ADMIN` with only necessary permissions for onboarding workflows.
`WORKER_ADMIN`	View and modify all worker-associated data, such as personal information, payment records, and so on.
`WORKER_ONBOARDING_ADMIN`	Same as `WORKER_ADMIN` with only necessary permissions for onboarding workflows.
`EMPLOYER_SUPER_ADMIN`	Grants the same permissions as the corresponding admin role, plus privileged sensitive actions such as unmasking full bank account numbers and government IDs (SSN/TIN)
`EMPLOYER_ONBOARDING_SUPER_ADMIN`	Same as `EMPLOYER_SUPER_ADMIN` with only necessary permissions for onboarding workflows.
`WORKER_SUPER_ADMIN`	Grants the same permissions as the corresponding admin role, plus privileged sensitive actions such as unmasking full bank account numbers and government IDs (SSN/TIN)
`WORKER_ONBOARDING_SUPER_ADMIN`	Same as `WORKER_SUPER_ADMIN` with only necessary permissions for onboarding workflows.

Deprecated roles

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

Deprecated	Replacement
`WORKER_USER`	`WORKER_ADMIN`
`WORKER_ONBOARDING`	`WORKER_ONBOARDING_ADMIN`
`EMPLOYER_ONBOARDING`	`EMPLOYER_ONBOARDING_ADMIN`