Authentication

Every request to the Sotion API carries an API key as a bearer token. A key belongs to one site, and only Owners of your team can create one, on the Pro and Scale plans and during the free trial.

How authentication works

Send the key in the Authorization header of every request. Every address starts with https://api.sotion.so/api/v1.

curl https://api.sotion.so/api/v1/members \
  -H "Authorization: Bearer so_your_api_key_here"

The key also decides which site a request works on, so no request names a site. The only address that needs no key is GET /health.

Create an API key

Keys live on the Integrations page of your site dashboard, under Advanced in the site's sidebar.

1. On the Integrations page, click Create Key.

2. Under Name, enter what the key is for, for example the tool that will use it. The name is required.

3. Click Create Key.

4. Copy the key into your tool.

You can copy it again later: open the menu at the end of the key's row and choose View Key. Keys created before keys could be viewed again show a message instead; roll one of those to get a key you can view.

Manage your API keys

The menu at the end of each key's row holds these actions. The row also shows when the key was created and when it was last used.

• Rename: changes the name. The key keeps working.

• Roll Key: revokes the key and creates a new one with the same name. Requests with the old key fail at once, so update your tool with the new one.

• Revoke: the key stops working at once. You can't undo this. The key stays in the list as Revoked.

• Delete: removes the key from the list, and it stops working.

A site can have 10 active keys. Revoked keys don't count toward the 10, so revoke or delete a key you no longer use before you create another.

Security best practices

• Treat a key like a password: anyone who has it can read and change your site's members and access groups.

• Never put keys in public repositories, chat logs or screenshots.

• Keep keys in environment variables or a secrets manager, not in your code.

• Create one key per tool, so you can revoke one without breaking the others.

• Roll a key when someone who had access to it leaves your team, or when you think it leaked.

Errors

An error answer is JSON with a code, a message and the HTTP status:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key.",
    "status": 401
  }
}

What's next

• API Overview: what the API covers, its responses and its rate limits.

• Webhooks Overview: get a message each time something happens on your site.