Provision a machine identity

Provisions a principal the account's automation can authenticate as: the gateway creates the OIDC client at the identity provider, mints the requested credential(s), returns them once, and stores the durable identity. The registry keeps no secret value — the response is the only copy, so record it now.

Reveal-once. credentials names which kinds to mint — secret (a client secret), api_key, or both, at most one of each. Each is returned in the credentials array of the response and nowhere else; a caller that drops the response rotates to recover.

The id is minted, not supplied. A durable sa_… handle the gateway assigns — the same value a token carries and a workspace roster names.

service_account only. Every other type is refused with 400. An agent identity is provisioned with its agent artifact through the agent extension, never here. The platform flavours (action, registry) are seated on every workspace in the account, so one created here would be an account-wide grant; the registry provisions those itself.

Any member may call this — provisioning is gated on organization#clients_create, which is member_access, so a machine identity for your own automation is an ordinary member operation. It is created_by you, which is what the credential sub-resource checks on every later mint/rotate/revoke: you may manage the identities you provisioned, and an account admin (organization#clients_manage) may manage anyone's.

Runs as the calling operator. The identity provider grants no machine-usable client-admin scope, so the caller's own bearer is forwarded; a synthetic principal with no token is refused 503.

Seated viewer on the org root. The new identity can read, and call, what the account shares in org_default — the built-in models among it — and nothing more; its spend is reported as yours. Any other workspace is a separate grant, because placing an identity there is that workspace's authority, not the account's: PUT /workspaces/{workspace_id}/members/{principal_id}.

Redirect URIs. redirect_uris (at most 10; absolute https, or http on localhost, 127.0.0.1 or [::1] only; no fragment, wildcard or userinfo; trimmed and de-duplicated) makes the client an authorization-code client: it is granted authorization_code and refresh_token beside client_credentials, openid and profile beside its contextplane:* scopes, a web application type, and PKCE. Your own runner drives the browser flow and redeems the code with the client secret, so a client with redirect URIs needs a secret: credentials then defaults to ["secret", "api_key"], and an explicit list without secret is 400. The gateway's OBO broker does not serve service accounts, and adds no callback of its own.

Scopes are a ceiling, not a grant. What the identity may do is what its workspace seats allow, cut down to what its scopes cover: contextplane:read reads, contextplane:write also creates and edits, contextplane:manage also deletes and governs workspaces and their members, and oauth-clients:manage provisions and administers machine identities. A scope never adds what the seats do not hold. The registry's own routes currently record what a credential's scopes would refuse rather than refusing it; the identity provider's OAuth-client routes already require oauth-clients:manage. oauth-clients:manage is for machine-only identities: with redirect_uris it is 400.

Defaults. Every field is optional: principal_type is service_account, credentials is ["api_key"] (["secret", "api_key"] with redirect_uris), scopes is ["contextplane:read", "contextplane:write", "contextplane:manage"], and an api_key lives credential_ttl_seconds = 7776000 (90 days). expires_in_seconds, the Control Plane's name for the same lifetime, is accepted as an alias; sending both is 400. An unknown field is 400, so a caller still sending the retired register-only client_id/secret_ref is told rather than ignored.

display_name, redirect_uris and scopes can change afterwards (PATCH); a machine identity's client_id and principal_type are what it is.