> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.usepassport.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.usepassport.ai/_mcp/server. # Revoke an access grant DELETE https://api.usepassport.ai/public/v1/access-grants/{accessGrantId} 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. Reference: https://docs.usepassport.ai/api-reference/access-grants/revoke-access-grant ## Authentication - `Authorization` header (bearer token, required) — 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. ## Request ### Path parameters - `accessGrantId` (string, required) — The grant's `id` (from the list). A non-UUID value is rejected with 400. ### Headers - `Idempotency-Key` (string, optional) — 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 ### 200 OK - `data` (AccessGrant, required) — 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). ## Errors ### 400 Bad Request Error The request body or query is invalid. - `error` (ErrorError, required) ### 401 Unauthorized Error Missing or invalid API key. Unlike every other response, this one carries no `RateLimit-*` headers: the request is rejected before a key is resolved, so there is no per-key window to report. Rejection happens at the gateway, which renders this same schema (and negotiates `application/problem+json` identically). - `error` (ErrorError, required) ### 403 Forbidden Error Authenticated but lacking required role (e.g. member key on a catalog mutation). - `error` (ErrorError, required) ### 404 Not Found Error Access grant not found (or not in the caller's organization). - `error` (ErrorError, required) ### 409 Conflict Error A request with this `Idempotency-Key` is still being processed. The original is in flight; retry after `Retry-After` seconds to receive its stored response. - `error` (ErrorError, required) ### 422 Unprocessable Entity Error This `Idempotency-Key` was already used with a different request body or path. The first request's response is never substituted — use a new key, or resend the original request unchanged. - `error` (ErrorError, required) ### 429 Too Many Requests Error Rate limit exceeded. - `error` (ErrorError, required) ### 500 Internal Server Error Unexpected server error. - `error` (ErrorError, required) ### 503 Service Unavailable Error Temporary unavailability (auth dependency down, encryption-config resolution failure, or discovery document unloadable). - `error` (ErrorError, required) ## Types ### AccessGrant 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). - `id` (string, optional) - `userId` (string, optional) — The WorkOS user the grant is for (`user_...`). - `namespaceId` (string, optional) - `namespaceName` (string, optional, nullable) — Resolved namespace name (soft-delete-inclusive); null when unresolvable. - `scopeType` (enum, optional) — What the grant authorizes. - Allowed values: `endpoint`, `resource_group`, `host`, `namespace` - `scopeValue` (string, optional) — The scoped id or value, by `scopeType`: resource_endpoint id, resource_group id, namespace id, or a hostname. - `scopeName` (string, optional, nullable) — Display name for a non-endpoint scope — the resource-group or namespace name, or the hostname itself. Null for endpoint scopes, which carry `endpoint` instead. - `endpoint` (AccessGrantEndpoint, optional, nullable) — Method/host/path of the scoped endpoint, populated only for `scopeType: endpoint` (null otherwise, or when the endpoint can no longer be resolved). - `status` (enum, optional) — Derived effective status: `expired` is computed from `expiresAt` at read time, never stored. - Allowed values: `active`, `revoked`, `expired` - `reason` (string, optional, nullable) — Provenance, e.g. `access_request:` for grants minted by approval. - `expiresAt` (datetime, optional, nullable) — Absolute expiry, or null for an unlimited grant. - `revokedAt` (datetime, optional, nullable) — When the grant was revoked; null for non-revoked grants. - `createdAt` (datetime, optional, nullable) - `updatedAt` (datetime, optional, nullable) ### ErrorError - `code` (enum, required) — The machine-readable failure reason. Treat a value not listed here as a generic failure of the class implied by the HTTP status, and do not assume retry behaviour for it — new codes may be added. - Allowed values: `VALIDATION_ERROR`, `MALFORMED_JSON`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `CONFLICT`, `UNPROCESSABLE_ENTITY`, `PAYLOAD_TOO_LARGE`, `RATE_LIMITED`, `INTERNAL_ERROR`, `SERVICE_UNAVAILABLE` - `message` (string, required) - `details` (list of FieldError, optional) ### AccessGrantEndpoint Method/host/path of the scoped endpoint, populated only for `scopeType: endpoint` (null otherwise, or when the endpoint can no longer be resolved). - `method` (string, optional) - `host` (string, optional) - `path` (string, optional) ### FieldError - `field` (string, optional) - `message` (string, optional) ## Examples **Response** ```json { "data": { "id": "7b3f2c1d-8e9a-4b5c-6d7e-8f9a0b1c2d3e", "userId": "user_01ABC", "namespaceId": "3f7c2b6e-1c2d-4a5b-9e8f-0a1b2c3d4e5f", "namespaceName": "Payments", "scopeType": "endpoint", "scopeValue": "c4d2e1f0-1111-2222-3333-444455556666", "scopeName": null, "endpoint": { "method": "POST", "host": "api.stripe.com", "path": "/v1/charges" }, "status": "revoked", "reason": "access_request:1f0a9b8c-7d6e-5f4a-3b2c-1d0e9f8a7b6c", "expiresAt": "2026-02-01T00:00:00.000Z", "revokedAt": "2026-01-10T09:00:00.000Z", "createdAt": "2026-01-02T10:15:00.000Z", "updatedAt": "2026-01-10T09:00:00.000Z" } } ``` **SDK Code** ```python default import requests url = "https://api.usepassport.ai/public/v1/access-grants/accessGrantId" headers = {"Authorization": "Bearer "} response = requests.delete(url, headers=headers) print(response.json()) ``` ```javascript default const url = 'https://api.usepassport.ai/public/v1/access-grants/accessGrantId'; const options = {method: 'DELETE', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go default package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.usepassport.ai/public/v1/access-grants/accessGrantId" req, _ := http.NewRequest("DELETE", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby default require 'uri' require 'net/http' url = URI("https://api.usepassport.ai/public/v1/access-grants/accessGrantId") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Delete.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java default import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.delete("https://api.usepassport.ai/public/v1/access-grants/accessGrantId") .header("Authorization", "Bearer ") .asString(); ``` ```php default request('DELETE', 'https://api.usepassport.ai/public/v1/access-grants/accessGrantId', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp default using RestSharp; var client = new RestClient("https://api.usepassport.ai/public/v1/access-grants/accessGrantId"); var request = new RestRequest(Method.DELETE); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift default import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.usepassport.ai/public/v1/access-grants/accessGrantId")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "DELETE" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```