Revoke an access grant
Revoke one grant by id. Admin only (a member key is rejected with 403). The revoke is a soft delete (status flips to revoked, the row is kept for history) and is idempotent — revoking an already-revoked grant returns 200 with the same body: the revoked grant. Revoking an expired grant is a no-op that returns 200 with the grant unchanged (status: expired, revokedAt: null), so its history is not rewritten. An optional Idempotency-Key makes a retry replay the stored response; reusing a key against a different grant is a 422. A non-UUID id is rejected with 400; a grant from another organization is invisible and returns 404.
Authentication
WorkOS API key (Authorization: Bearer sk_…). Scope comes from the key’s permissions: a key carrying passport:admin has admin scope (full catalog CRUD), any other key has member scope (reads + access requests). Organization-owned keys are admin by ownership and carry no associated user; keys minted for a user carry theirs, which is what access requests and createdBy are attributed to.
Path parameters
The grant’s id (from the list). A non-UUID value is rejected with 400.
Headers
Optional idempotency key, retained 24h and bound to the request that first used it. Resending the same request replays the stored response (with Idempotent-Replayed: true); reusing the key with a different body or path returns 422; retrying while the original is still in flight returns 409 with Retry-After. A failed request releases its key.
Response headers
Response
A live access grant — who (userId) can reach what scope in a namespace. Minted when an access request is approved; revoke flips status to revoked and stamps revokedAt while keeping the row for history. teamId is omitted (implicit from the API key’s organization).