Authentication and scopes

Back to the guide

Two ways to reach the API, and the difference matters.

API keys

Authorization: Bearer sf_live_…

A key holds scopes, each optionally narrowed to particular objects.

Three rules shape what is possible:

A key only gets scopes its creator holds. An admin cannot create a key more capable than an admin.

A key is never an owner, so it never inherits the owner exemption from restricted records.

Scopes and visibility are different checks, and both must pass. A scope allows an action. It never reveals anything. What a key can see is decided by record permissions through its own service account.

Two checks, not one

This is the part worth getting right in your head before debugging anything.

A scope of records:read does not mean every record. It means reading records is an allowed kind of action for this key. Which records come back is a separate question, answered by the same permission rules that apply to a person.

So a key with records:read that returns nothing for a restricted record is working correctly. Grant that key access under Settings → Access and permissions and the same call starts returning it.

Not found, not forbidden

Anything outside a key's reach returns 404, the same as something that does not exist.

That is deliberate. Returning forbidden would confirm the record exists, which is itself a disclosure. Do not treat a 404 as proof that an id is wrong.

OAuth connections

For an application acting on behalf of a person, use OAuth. The connection acts as that person and is bound by their role.

Their role is checked on every request, not at approval. If the person is demoted, the connection loses access on its next call; if they leave, it stops working.

See Connecting an app with OAuth.

Next

• Errors, paging and rate limits
• The MCP server