> 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.

# Create an access request

POST https://api.usepassport.ai/public/v1/access-requests
Content-Type: application/json

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`).


Reference: https://docs.usepassport.ai/api-reference/access-requests/create-access-request

## 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

### 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.

### Body (application/json)

This endpoint expects an AccessRequestCreate.

- `namespaceId` (string, required)
- `entities` (list of AccessRequestEntity, required)
- `requesterId` (string, optional, nullable) — 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`.
- `email` (string, optional, nullable) — 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`.
- `message` (string, optional, nullable)
- `durationDays` (enum, optional)
  - Allowed values: `7`, `30`, `90`

## Response

### 201

Created

- `data` (AccessRequest, required)

## 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

Namespace not found (or not owned by 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

### AccessRequestEntity

- `type` (enum, required)
  - Allowed values: `resource_group`, `resource_endpoint`
- `id` (string, required)

### AccessRequest

- `id` (string, optional)
- `requesterId` (string, optional)
- `namespaceId` (string, optional)
- `status` (enum, optional)
  - Allowed values: `pending`, `approved`, `rejected`, `cancelled`
- `message` (string, optional, nullable)
- `durationDays` (enum, optional)
  - Allowed values: `7`, `30`, `90`
- `entities` (list of AccessRequestEntity, optional)
- `decisionReason` (string, optional, nullable)
- `decidedBy` (string, optional, nullable)
- `decidedAt` (datetime, optional, nullable)
- `autoApproved` (boolean, optional) — True when the system (not a human admin) decided this request.
- `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)

### FieldError

- `field` (string, optional)
- `message` (string, optional)

## Examples

**Request**

```json
{
  "namespaceId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "entities": [
    {
      "type": "resource_group",
      "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e"
    },
    {
      "type": "resource_endpoint",
      "id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f"
    }
  ],
  "message": "Need read access for CI",
  "durationDays": 30
}
```

**Response**

```json
{
  "data": {
    "id": "d4e5f6a7-4444-5555-6666-777788889999",
    "requesterId": "user_01ABC",
    "namespaceId": "3f7c2b6e-1c2d-4a5b-9e8f-0a1b2c3d4e5f",
    "status": "pending"
  }
}
```

**SDK Code**

```python default
import requests

url = "https://api.usepassport.ai/public/v1/access-requests"

payload = {
    "namespaceId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "entities": [
        {
            "type": "resource_group",
            "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e"
        },
        {
            "type": "resource_endpoint",
            "id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f"
        }
    ],
    "message": "Need read access for CI",
    "durationDays": 30
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript default
const url = 'https://api.usepassport.ai/public/v1/access-requests';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"namespaceId":"1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d","entities":[{"type":"resource_group","id":"2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e"},{"type":"resource_endpoint","id":"3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f"}],"message":"Need read access for CI","durationDays":30}'
};

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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usepassport.ai/public/v1/access-requests"

	payload := strings.NewReader("{\n  \"namespaceId\": \"1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d\",\n  \"entities\": [\n    {\n      \"type\": \"resource_group\",\n      \"id\": \"2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e\"\n    },\n    {\n      \"type\": \"resource_endpoint\",\n      \"id\": \"3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f\"\n    }\n  ],\n  \"message\": \"Need read access for CI\",\n  \"durationDays\": 30\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	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-requests")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"namespaceId\": \"1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d\",\n  \"entities\": [\n    {\n      \"type\": \"resource_group\",\n      \"id\": \"2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e\"\n    },\n    {\n      \"type\": \"resource_endpoint\",\n      \"id\": \"3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f\"\n    }\n  ],\n  \"message\": \"Need read access for CI\",\n  \"durationDays\": 30\n}"

response = http.request(request)
puts response.read_body
```

```java default
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.usepassport.ai/public/v1/access-requests")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"namespaceId\": \"1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d\",\n  \"entities\": [\n    {\n      \"type\": \"resource_group\",\n      \"id\": \"2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e\"\n    },\n    {\n      \"type\": \"resource_endpoint\",\n      \"id\": \"3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f\"\n    }\n  ],\n  \"message\": \"Need read access for CI\",\n  \"durationDays\": 30\n}")
  .asString();
```

```php default
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.usepassport.ai/public/v1/access-requests', [
  'body' => '{
  "namespaceId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "entities": [
    {
      "type": "resource_group",
      "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e"
    },
    {
      "type": "resource_endpoint",
      "id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f"
    }
  ],
  "message": "Need read access for CI",
  "durationDays": 30
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp default
using RestSharp;

var client = new RestClient("https://api.usepassport.ai/public/v1/access-requests");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"namespaceId\": \"1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d\",\n  \"entities\": [\n    {\n      \"type\": \"resource_group\",\n      \"id\": \"2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e\"\n    },\n    {\n      \"type\": \"resource_endpoint\",\n      \"id\": \"3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f\"\n    }\n  ],\n  \"message\": \"Need read access for CI\",\n  \"durationDays\": 30\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift default
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "namespaceId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "entities": [
    [
      "type": "resource_group",
      "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e"
    ],
    [
      "type": "resource_endpoint",
      "id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f"
    ]
  ],
  "message": "Need read access for CI",
  "durationDays": 30
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.usepassport.ai/public/v1/access-requests")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

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()
```