Skip to navigation

Create an access request

Submit a request for access to resource groups and/or endpoints in one namespace. An admin decides it with the approve/reject operations (admin key) or in the app. Both admin and member API keys may create requests.

The requester defaults to the user the API key belongs to. An admin key may override it with requesterId to file on someone else’s behalf; a member key may not (403). A key with no associated user — an organization-owned key, whose creator WorkOS does not record — must supply requesterId or email, or the request is rejected with 400: a request cannot be attributed to the key itself, because approval mints the grant against the requester and policy bundles resolve by user.

Instead of requesterId, an admin key may pass email (not both — 400). It is resolved to an active member of the key’s organization; no such member is a 400, and if the lookup cannot be completed the request fails with 503 (retry, or pass requesterId).

Authentication

AuthorizationBearer

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.

Headers

Idempotency-KeystringOptional

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.

Request

This endpoint expects an object.
namespaceIdstringRequiredformat: "uuid"
entitieslist of objectsRequired
requesterIdstring or nullOptionalformat: "^user_[A-Za-z0-9]{1,58}$"

The WorkOS user the access is for. Defaults to the user the key belongs to. An admin key may name any user; a member key may omit it or set it to its own user id, and any other value is rejected with 403. An organization-owned key, which has no associated user, must supply this or email. Mutually exclusive with email.

emailstring or nullOptionalformat: "email"<=254 characters

Email of the user the access is for, as an alternative to requesterId. Admin keys only (403 for a member key). Must belong to an active member of the key’s organization (400 otherwise); the response carries the resolved requesterId. Mutually exclusive with requesterId.

messagestring or nullOptional<=1000 characters
durationDaysenumOptional
Allowed values:

Response headers

RateLimit-LimitintegerOptional
Requests allowed in the current window.
RateLimit-RemainingintegerOptional
Requests remaining in the current window.
RateLimit-ResetintegerOptional
Unix epoch seconds when the window resets.

Response

Created
dataobject

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error