Skip to navigation

List access grants

List the team’s access grants — the live records minted when an access request is approved, each revocable by its id. Admin only (a member key is rejected with 403). Optional userId, namespaceId, scopeType, and status filters (combined with AND) plus cursor pagination. status is the derived effective status: an active grant whose expiresAt has passed reads as expired.

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.

Query parameters

limitintegerOptional1-100Defaults to 50

Page size (1–100, default 50).

cursorstringOptional

Opaque pagination cursor from a previous page’s pagination.nextCursor.

userIdstringOptional

Narrow to the grants of one WorkOS user (user_...). Pass it once; a repeated parameter is rejected with 400.

namespaceIdstringOptionalformat: "uuid"

Narrow to the grants in one namespace. Must be a UUID (400 otherwise).

scopeTypeenumOptional

Narrow to one kind of grant scope (what the grant authorizes).

Allowed values:
statusenumOptional

Narrow by the derived effective status. expired is an active grant whose expiresAt has passed; revoked grants stay listed as history.

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

OK
datalist of objects
paginationobject

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error