> 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/oauth.md). # OAuth {% @scale-docs-page-title/page-title title="OAuth" %} {% hint style="warning" %} **Confirm before publishing:** Whether delegated OAuth ships in the first public release; the issuer and discovery URL; authorization, token and revocation endpoints; client registration and redirect URI policy; approved scopes; token lifetime; refresh-token rotation; brokerage consent; and the provider that issues tokens. No public ScaleConnect OAuth registration or token endpoint has been verified. The request shapes below describe the intended authorization-code flow with PKCE, not callable Scale endpoints. {% endhint %} Use OAuth when an application acts on behalf of a signed-in person. The application receives a scoped token after that person authorizes access. Server integrations that do not act for a person use API Keys. ## Connect a user 1. Register the application and its exact redirect URI. 2. Create a random `state` and a PKCE `code_verifier`; derive the S256 `code_challenge`. 3. Redirect the user to the approved authorization endpoint. 4. After sign-in and consent, validate the returned `state` and exchange the code with the verifier. 5. Store tokens securely and call only the resources allowed by the user's current role and the granted scopes. The authorization request will have this shape after the issuer is selected: ```http GET ?response_type=code&client_id=&redirect_uri=&scope=&state=&code_challenge=&code_challenge_method=S256 ``` The application's server exchanges the returned code: ```http POST Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=&redirect_uri=&client_id=&code_verifier= ``` The exact response schema and token lifetime must come from the chosen issuer. A successful response is expected to provide an access token, token type, expiry and the granted scopes; a refresh token is present only when the approved flow issues one. Do not put a client secret or refresh token in a browser URL. ## Call the API ```http GET /v1/ Authorization: Bearer Accept: application/json ``` A token's scopes set the upper limit of access. The API must also check the caller's current brokerage membership, client book and resource permission on every request. Consent to a brokerage does not grant access to every client in it. ## Token expiry and lost access When an access token expires, use the issuer's approved refresh flow if a refresh token was issued; otherwise send the user through authorization again. If the user revokes consent, leaves a brokerage or loses access to a client, resource requests must stop succeeding even while a token remains unexpired. Treat `401` as a credential problem and `403` as a permission problem. Do not retry a forbidden write automatically. ## Before a client can integrate The published reference needs a real registration process, issuer metadata, exact endpoint URLs, request and response examples, consent screenshots, a scope-to-operation map and tested error responses. Those details belong in this page once the contract is implemented and verified. --- # 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/oauth.md?ask=&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.