> 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/api-keys.md).

# API Keys

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

{% hint style="warning" %}
**Confirm before publishing:** Key prefix and length; issuance UI/API; exact scope names; brokerage binding; expiration; rotation overlap; error body; rate limits; IP allowlisting; and audit retention. The `sc_live_` prefix and `/v1/integrators/me` below are from the partner API design. A deployed integrator key guard has not been verified.
{% endhint %}

Use an API key for a trusted server-to-server integration. Create a separate key for each service and environment. A key belongs to an integrator or one brokerage, carries specific scopes and is checked on every request. Never place it in a browser bundle, mobile app or URL.

## Make the first request

```http
GET /v1/integrators/me HTTP/1.1
Host: <approved-api-host>
Authorization: Bearer sc_live_<secret>
Accept: application/json
```

The intended `/me` response identifies the integrator, its brokerage binding if present, status and granted scopes. Check those values before starting a sync. The exact response DTO must be published from the implemented route.

## Create a key

1. An authorized administrator selects the integrator or brokerage and the smallest set of scopes the service needs.
2. Copy the secret when it is issued. The raw value should be shown once; store it in a secret manager.
3. Call `/v1/integrators/me` from the target environment and verify the identity and grants.
4. Record the key's owner and rotation date in the integration's operations record.

A broker-scoped key must be limited to the issuing brokerage's book. A scope never overrides resource-level access checks.

## Scope groups

| Workflow                       | Proposed scopes                                |
| ------------------------------ | ---------------------------------------------- |
| Read client and portfolio data | `clients:read`, `portfolio:read`, `loans:read` |
| Import or synchronize data     | `sync:write`                                   |
| Read and write actuals         | `actuals:read`, `actuals:write`                |
| Read brokerage information     | `broker:read`, `commissions:read`              |
| Read and write notes           | `notes:read`, `notes:write`                    |
| Read and write reviews         | `reviews:read`, `reviews:write`                |
| Manage webhooks                | `webhooks:read`, `webhooks:write`              |

These are proposed names. Each operation in the ScaleConnect REST API must state its exact required scopes before release.

## Rotate or revoke

Create a replacement with the same approved grants, deploy it, verify `/me` and a representative read, then revoke the old key. The design proposes a 24-hour overlap, which must be confirmed in the running guard. Revoke immediately after suspected exposure. Revocation blocks new requests; it does not undo completed writes or deliveries.

A missing, invalid, expired or revoked key is intended to return `401`; a valid key without a required scope or brokerage access returns `403`. The final reference must define stable machine-readable error codes and a response example. A rate-limited request should return `429` with `Retry-After` once limits are implemented.


---

# 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/api-keys.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.