> ## Documentation Index
> Fetch the complete documentation index at: https://docs-v2.sortx.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and API keys

> How people sign in to SortX, and how an integration authenticates with a scoped API key.

## People sign in once, everywhere

Staff, tenants, landlords, contractors and the mobile apps all sign in through one SortX sign-in
service at `auth.sortx.co.uk`. The staff app, the portals, the API and the MCP server all trust
that service, so a person's role and workspace are checked the same way whichever surface they
use. Sign-up is closed: people join a workspace by invitation.

Integrations do not use a person's sign-in. They use an **API key**.

## Create an API key

Only a **workspace owner** can create or revoke keys.

<Steps>
  <Step title="Open Settings → API keys">
    In the staff app, go to **Settings → Automation and integrations → API keys**.
  </Step>

  <Step title="Name the key and choose its permissions">
    Give each integration its own key. Tick only the permissions it needs (see
    [Scopes](#scopes)) and choose when it expires: 7, 30, 90 or 365 days.
  </Step>

  <Step title="Copy it now">
    The key is shown once. Store it in your integration's secret store. If you lose it, revoke
    it and create another.
  </Step>
</Steps>

Revoking a key stops it immediately, for both the API and the MCP server.

## Send the key

Send the key in the `x-api-key` header. A key belongs to one workspace, so nothing else is
needed:

```bash theme={null}
curl https://api.sortx.co.uk/<path> \
  -H "x-api-key: $SORTX_API_KEY"
```

You may also send `X-Tenant: <workspace-slug>`. If you do, it must be the key's own workspace,
or the request is refused. This guards against a key being used against the wrong workspace by
mistake.

Do not send a key as `Authorization: Bearer <key>`. A bearer token is a signed-in person's
session (it is how the SortX apps call the API, always with `X-Tenant`), so a key sent there is
refused.

## Scopes

Every endpoint belongs to a group, and every key permission is `<group>:read` (GET requests) or
`<group>:write` (everything else). A key without the scope for an endpoint gets a `403`. The
settings page lists the groups you can grant; the [API reference](/api-reference/introduction)
shows each endpoint's group.

Some things a key can never do, whatever its scopes, because they belong to the owner as a
person: create or revoke other keys, change workspace settings, or change billing.

## Limits

Each key has a fair-use request budget. When it is spent the API answers `429` with a
`Retry-After` header (and `retryAfterSeconds` in the body). Wait that long and retry.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.