# Organization-scoped API keys

Your OhAuthCat secret API keys can be limited to a single organization. Use one when a service, a contractor or an automation should only see one customer.

- An organization key can only read and change that organization's resources, through routes that name the organization. Any other request is refused with [`api_key_organization_forbidden`](/errors/api_key_organization_forbidden/) (403), checked centrally for every route. See [what an organization key can call](#what-an-organization-key-can-call).
- A key can hold up to 4 extra secrets next to its main one, each with its own last-used time, so you can hand different secrets to different systems and revoke one without rolling the key. Adding a fifth answers [`api_key_secret_limit`](/errors/api_key_secret_limit/).

## What an organization key can call

A request with an organization key must name the key's organization, in one of two ways:

- **In the path.** Any route with `{org}` in its path, such as `GET /v1/organizations/{org}/domains` or `PUT /v1/organizations/{org}/user_management_settings`, with the key's organization as `{org}`.
- **In the `organization` query parameter**, on the list routes that filter by it:

| Route                                                                                                     |
| --------------------------------------------------------------------------------------------------------- |
| `GET /v1/connections`, `GET /v1/directories`, `GET /v1/users`, `GET /v1/invites`                          |
| `GET /v1/events`, `GET /v1/audit_logs`, `GET /v1/audit_log_events`, `GET /v1/audit_log_events/export`     |
| `GET /v1/requests`, `GET /v1/sign_ins`, `GET /v1/connection_health`                                       |
| `GET /v1/portal/links`, `GET /v1/portal/invites`, `GET /v1/passport/links`                                |
| `GET /v1/authorization/roles`, `GET /v1/m2m_clients`, `GET /v1/oauth/grants`, `GET /v1/pipes/connections` |
| `GET /v1/encryption_keys/setup`, `GET /v1/vault/keys`                                                     |
| `GET` and `DELETE /v1/vault/objects/{name}`, `GET /v1/vault/objects/{name}/versions`                      |

On every other route an `organization` or `organization_id` query parameter does not count, because the route would not filter by it. A value that names another organization is refused on any route.

Routes that reach a resource by its ID alone are refused for organization keys, since the ID does not prove which organization the resource belongs to:

- Connections: `GET`, `PATCH` and `DELETE /v1/connections/{conn}`.
- Directories: `GET`, `PATCH` and `DELETE /v1/directories/{dir}`.
- Users: `GET`, `PATCH` and `DELETE /v1/users/{user}`, the user's passkey routes, and `POST /v1/user_management/passkeys/authentication_options` and `/authenticate`.
- M2M clients: `POST /v1/m2m_clients` and every `/v1/m2m_clients/{client}` route.
- Webhook endpoints: every `/v1/webhook_endpoints` route, since endpoints belong to the environment.
- Imports: `POST /v1/imports/{imp}/organizations/{org}/switch` and `/rollback`, even though they name an organization, because they switch live sign-in routing.

What to use instead:

- To read, list with the organization filter: `GET /v1/connections?organization=<org>`, `GET /v1/directories?organization=<org>`, `GET /v1/users?organization=<org>` or `GET /v1/m2m_clients?organization=<org>`.
- To change one of these resources, or for webhooks and imports, use an environment-wide secret key on your server.

For example, an organization key lists its connections with:

```http
GET /v1/connections?organization=org_01J9Z3K5V7W8X9Y0Z1A2B3C4D5 HTTP/1.1
Host: api.ohauthcat.com
Authorization: Bearer <organization key>
```

## Manage keys

In the dashboard under API keys, or with the management API (scopes `api_keys:read` and `api_keys:write`):

| Route                                                                 | Does                                   |
| --------------------------------------------------------------------- | -------------------------------------- |
| `GET`, `POST /v1/organizations/{org}/api_keys`                        | List or create the organization's keys |
| `GET /v1/organizations/{org}/api_keys/{key}`                          | Read one key                           |
| `POST /v1/organizations/{org}/api_keys/{key}/roll`                    | Replace the key's secret               |
| `POST /v1/organizations/{org}/api_keys/{key}/revoke`                  | Revoke the key                         |
| `GET`, `POST /v1/organizations/{org}/api_keys/{key}/secrets`          | List or add extra secrets              |
| `POST /v1/organizations/{org}/api_keys/{key}/secrets/{secret}/revoke` | Revoke one extra secret                |

- A secret is shown once, when it is created or rolled; those answers are sent with `Cache-Control: no-store`.
- A key can be given only scopes the calling key holds, and rolling a key or adding a secret needs every scope of the target key. Otherwise the answer is [`api_key_scope_missing`](/errors/api_key_scope_missing/).
- An organization key reaches only its own organization's keys. Another organization's key, an environment-wide key or a revoked key answers 404.
- Each change is recorded in your audit log (`api_key.created`, `api_key.rolled`, `api_key.revoked`, `api_key.secret_created`, `api_key.secret_revoked`).

From the CLI: `ohauthcat api-keys list|get|create|roll|revoke` and `ohauthcat api-keys secrets list|create|revoke`. In Terraform: [`ohauthcat_organization_api_key`](/terraform/).

## Allowed intents

`GET` and `PUT /v1/organizations/{org}/allowed_intents` (scopes `organizations:read` and `organizations:write`) read and set which [setup-portal intents](/hosted-portal/intents/) the organization may use. From the CLI: `ohauthcat allowed-intents get|set`; in Terraform: `ohauthcat_organization_allowed_intents`.
