Skip to main content

How authentication works in the Sally API

Every request to the Sally API, except the health check, carries a bearer token in the Authorization header. This page explains which tokens exist, what a token is allowed to see and how to find out who a token belongs to.

Authorization: Bearer <token>

Quick navigation

  1. Two kinds of token
  2. What a token may access
  3. Find out who you are
  4. Keep tokens safe

1. Two kinds of token​

  • Personal access token with the prefix sally_user_api_. You create it in Sally under Settings > Integrations > Personal Access Token. It is bound to your user and does not expire unless you set an expiry date. This is the right choice for an integration you run yourself, and the one the Quickstart uses.
  • OAuth 2.1 access token issued by Sally. This is the right choice when you build something that other companies install and sign in to with their own Sally account.

2. What a token may access​

A token acts as the user it belongs to. It reaches exactly the company accounts that user is a member of, with that user's role and visibility. There is no separate permission model to learn: if the person cannot see a recording in the app, the token cannot see it either.

Important

You notice this in the status codes. Something you are not allowed to see answers 404, not 403, so a response never reveals that the data exists. A 403 means the opposite: the resource exists and you can see it, but the operation needs a higher role, for example admin or owner. Errors lists all status codes.

3. Find out who you are​

Two calls tell you who the token belongs to and which company accounts it can address:

curl "https://api.sally.io/v1.0/me" \
  -H "Authorization: Bearer $SALLY_TOKEN"

4. Keep tokens safe​

Recommendation

Treat a token like a password. Send it only in the Authorization header, never in a URL. Give it an expiry date if the integration is temporary, and revoke a token in Sally as soon as nobody needs it any more.