Organization credentials

One key shared by a whole tenant — managed by its manager roles, served to every member.

An organization credential is owned by a tenant, not a person: the server sets owner_type=organization and owner_id to the org_id claim of your token. One record serves the whole team — store the shared vendor key once, rotate it once, instead of copying it into every member's personal credentials.

The API is a mirror

/v1/org-credentials mirrors Personal Credentials endpoint-for-endpoint — create, list, get, PATCH-rotate, make-default, disable/enable, delete — with identical semantics (defaults, versions, soft delete) plus an owner_id field in responses. What differs is who may call it.

Access: manager roles only

Both reads and writes require the caller to be a manager of the organization. Two gates apply, both answering 403 FORBIDDEN:

1. The usual role gate: user/provider_admin mutate, auditor reads only.
2. The organization gate: your token must carry an org_id, and your raw organization role (as issued by the identity provider — owner, admin, member, viewer) must be in the service's manager list (JWT_ORG_MANAGER_ROLES, default owner and admin).

The reasoning: the organization's secret inventory — even masked — is its administrators' business. A member needs to know whether translation will work, and for that there is Credential Status, which any role may call and which reports the organization level without exposing a single record.

Isolation between organizations is absolute: records of another tenant answer 404, and the audit trail records the acting user's sub as the actor on every change.

What members experience

Once a manager stores an organization default for a provider, resolve serves it to every member without a personal credential — the chain is USER → ORGANIZATION → PLATFORM. A member with their own key keeps using their own; disable the org record and members fall through to the platform level (where allowed).

Worked example, including the 403 a non-manager sees: cookbook scenario 05.