Skip to content
Dashboard
Theme
Theme

Organization-scoped API keys

Limit an OhAuthCat API key to one organization and give a key several secrets.

View Markdown

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.

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:

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

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.
  • 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.

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