> ## Documentation Index
> Fetch the complete documentation index at: https://docs.accessowl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Use the AccessOwl API to manage access requests, applications, policies, and users programmatically.

The AccessOwl API is a REST API that lets you manage access requests, revocations,
applications, policies, and users programmatically.

## Base URL

All requests are made to:

```
https://api.accessowl.com
```

The current API version is `v1`, so every endpoint is prefixed with `/api/v1`.

## Authentication

The API uses **Bearer token authentication**. Pass your AccessOwl API token in the
`Authorization` header on every request:

```bash theme={null}
curl https://api.accessowl.com/api/v1/applications \
  -H "Authorization: Bearer <your-api-token>"
```

API tokens are created and managed from within AccessOwl by an organization admin.
Treat tokens as secrets: store them securely and never commit them to source control.
Requests without a valid token return `401 Unauthorized`.

## Rate limiting

Each API token is limited to **1,000 requests per hour**. Exceeding the limit returns
`429 Too Many Requests` with a `Retry-After` header indicating how many seconds to
wait before retrying:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 42
```

When you receive a `429`, pause for the number of seconds in `Retry-After` before
sending further requests.

## Idempotency

Mutating requests (`POST`, `PUT`, `PATCH`, `DELETE`) accept an optional
`Idempotency-Key` header so a retried request doesn't perform the same operation
twice.

```bash theme={null}
curl -X POST https://api.accessowl.com/api/v1/access_revocations \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Idempotency-Key: 8f3a1c2e-..." \
  -H "Content-Type: application/json" \
  -d '{ "access_state_id": "...", "reason": "..." }'
```

Generate a unique key for each operation you want to make idempotent. We recommend a
V4 UUID, or another random string with enough entropy to avoid collisions. The key
must be 1–255 characters and is remembered for 14 days.

Unlike some APIs, AccessOwl does **not** replay the original response. Instead, the
first request with a given key is processed normally and every later request reusing
that key is rejected:

* **Same key, same request body:** returns `409 Conflict`. The duplicate is not
  processed again. A `409` confirms that a request with this key was already
  received — it does **not** report the outcome of the original request, which may
  still have failed. If you need the result, query the relevant resource directly.
* **Same key, different request body:** returns `422 Unprocessable Entity`. A key
  must not be reused for a different operation.
* **Missing or malformed key:** returns `400 Bad Request`.

To retry safely after a network error or timeout, send the **same** request with the
**same** key. You'll either get the original response (if the first request hadn't
reached us) or a `409`, telling you the operation was already submitted and you
should not send it again.

## Responses

The API returns JSON. Successful requests return a `2xx` status code; client and
server errors return `4xx` and `5xx` codes respectively, with an error payload
describing what went wrong.