> For the complete documentation index, see [llms.txt](https://docs.scaleconnect.com.au/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleconnect.com.au/api/authentication.md).

# Authentication

{% @scale-docs-page-title/page-title title="Authentication" %}

{% hint style="warning" %}
**Confirm before publishing:** the partner API key guard, OAuth issuer and consent flow, production API host, approved scope catalogue, token lifetimes, error body and rate-limit policy. Current R16 user tokens are an internal application credential; the partner key and delegated OAuth flows below are the intended public contract, not available credentials today.
{% endhint %}

Every API request needs an identity. The credential determines **who is calling**; the scopes and resource checks determine **what that caller can access**. A successful sign-in never grants access to another brokerage or client book.

## Choose a credential

| You are building                                 | Credential                                 | Access model                                                                                           |
| ------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| A server-to-server integration for one brokerage | [API key](/api/authentication/api-keys.md) | Integrator identity, assigned scopes and permitted client book                                         |
| An app acting for a signed-in person             | [OAuth](/api/authentication/oauth.md)      | Delegated user, consented scopes and the user's existing permissions                                   |
| A first-party R16 application                    | Product session bearer token               | Existing internal API; see the generated [ScaleApp REST reference](/api/rest-api/scaleapp-rest-api.md) |

Send the credential in the `Authorization` header:

```http
Authorization: Bearer <access_token_or_api_key>
Accept: application/json
```

Keep credentials in a server-side secret store. Do not put them in a URL, browser bundle, Git repository or webhook payload.

## How authorization is evaluated

1. The API validates the credential and resolves the caller.
2. The route checks the required scope or product permission.
3. The data service checks brokerage membership and client or resource reach.
4. The request is recorded with the caller, route, result and trace ID.

A client ID supplied by the caller is a **filter**, never proof of permission. The same rule applies to REST, GraphQL and MCP tools.

## Authentication failures

| HTTP status | Meaning                                         | What to do                                               |
| ----------- | ----------------------------------------------- | -------------------------------------------------------- |
| `401`       | Missing, invalid, expired or revoked credential | Obtain or rotate the credential; do not retry unchanged  |
| `403`       | Valid identity without scope or resource access | Request the required grant or choose an allowed resource |
| `429`       | Rate limit reached                              | Respect `Retry-After` if supplied                        |

Do not treat `404` as proof a resource does not exist; access-controlled resources may hide their existence. The exact machine-readable error codes are listed on the credential pages and must be checked against the implemented guard before publication.

## Next steps

* [API Keys](/api/authentication/api-keys.md): issue, store, rotate and revoke a server credential.
* [OAuth](/api/authentication/oauth.md): obtain delegated user access.
* [REST API](/api/rest-api.md): choose the correct API reference.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.scaleconnect.com.au/api/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.