Organization-scoped API keys
Limit an OhAuthCat API key to one organization and give a key several secrets.
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(403), checked centrally for every route. See 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.
What an organization key can call
Section titled “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 asGET /orv1/ organizations/ {org}/ domains PUT /, with the key’s organization asv1/ organizations/ {org}/ user_management_settings {org}. - In the
organizationquery 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 /, GET / |
GET /v1/requests, GET /v1/sign_ins, GET / |
GET /v1/portal/links, GET /v1/portal/invites, GET /v1/passport/links |
GET /, GET /v1/m2m_clients, GET /v1/oauth/grants, GET / |
GET /, GET /v1/vault/keys |
GET and DELETE /, GET / |
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,PATCHandDELETE /.v1/ connections/ {conn} - Directories:
GET,PATCHandDELETE /.v1/ directories/ {dir} - Users:
GET,PATCHandDELETE /v1/users/{user}, the user’s passkey routes, andPOST /andv1/ user_management/ passkeys/ authentication_options /authenticate. - M2M clients:
POST /v1/m2m_clientsand every/route.v1/ m2m_clients/ {client} - Webhook endpoints: every
/v1/webhook_endpointsroute, since endpoints belong to the environment. - Imports:
POST /andv1/ imports/ {imp}/ organizations/ {org}/ switch /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 /orv1/ users? organization=<org> 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:
GET /v1/connections?organization=org_01J9Z3K5V7W8X9Y0Z1A2B3C4D5 HTTP/1.1Host: api.ohauthcat.comAuthorization: Bearer <organization key>Manage keys
Section titled “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 / |
List or create the organization’s keys |
GET / |
Read one key |
POST / |
Replace the key’s secret |
POST / |
Revoke the key |
GET, POST / |
List or add extra secrets |
POST / |
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. - 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| and ohauthcat api-keys secrets list|. In Terraform: ohauthcat_organization_api_key.
Allowed intents
Section titled “Allowed intents”GET and PUT / (scopes organizations:read and organizations:write) read and set which setup-portal intents the organization may use. From the CLI: ohauthcat allowed-intents get|; in Terraform: ohauthcat_organization_allowed_intents.