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

# API Overview

Programmatic access to your Oleria workspace, secured with OAuth 2.0 Client Credentials. The Oleria API is a REST API - all endpoints use standard HTTP methods and return JSON bodies. Versioning is part of the URL path so breaking changes can ship without disrupting your existing integrations.

## Environments

Your API base URL is shown in the **API URL** field when you create an OAuth application in **Settings → Manage APIs**. It follows the pattern:

```
https://devx.YOUR_TENANT.oleria.io
```

Use this URL as the base for all API calls.

## Authentication

The API uses the OAuth 2.0 Client Credentials grant. You exchange a `client_id` and `client_secret` for a short-lived JWT, then send it as a `Bearer` credential in the `Authorization` header on every request.

```
Authorization: Bearer <access_token>
```

Tokens are typically valid for one hour. Cache the token in your client and refresh it just before expiry rather than minting one per request. See [Generate an API Token](/developer-docs/api-reference/generate-token) for the full flow, response shape, troubleshooting, and rotation guidance.

## Conventions

| Convention  | Detail                                                                                                                                                                                                           |
| :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Versioning  | Version is part of the URL path - currently `/v1/`. Breaking changes will ship under a new path prefix.                                                                                                          |
| Timestamps  | ISO 8601, UTC (for example, `2026-05-12T17:32:00Z`).                                                                                                                                                             |
| Encoding    | UTF-8.                                                                                                                                                                                                           |
| Idempotency | Send an `Idempotency-Key` header on requests that change data. Resending the same request with the same key returns the job the first one created instead of applying the change twice. Use one key per request. |

## Errors

Oleria uses conventional HTTP status codes to indicate success or failure. Error responses include a stable JSON body with `code` and `message` fields you can branch on.

| Status | Meaning                                                                                                                                                          |
| :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`  | Request succeeded.                                                                                                                                               |
| `201`  | A new resource was created.                                                                                                                                      |
| `202`  | Accepted - the change was accepted and is being applied in the source application. The response carries an action job id; poll the job for the outcome.          |
| `400`  | Bad Request - the request body or parameters are invalid.                                                                                                        |
| `401`  | Unauthorized - missing, expired, or malformed access token.                                                                                                      |
| `403`  | Forbidden - the credential is not permitted on this resource.                                                                                                    |
| `404`  | Not Found - the resource does not exist or is not visible to this credential.                                                                                    |
| `409`  | Conflict - the request is valid and permitted, but the state of something forbids it. Branch on `code` to tell the cases apart.                                  |
| `429`  | Too Many Requests - rate limit exceeded.                                                                                                                         |
| `501`  | Not Implemented - the operation is part of the contract but is not available in your deployment yet. Nothing went wrong and retrying will not change the answer. |
| `5xx`  | Server error on Oleria's side.                                                                                                                                   |

## Rate limits

The Oleria API enforces per-tenant rate limits to protect platform stability. When you exceed your limit, the API returns `429 Too Many Requests` with a `Retry-After` response header (in seconds). Implement exponential back-off in your client to avoid compounding pressure on the gateway.

## Example request

Once you have an access token (see [Generate an API Token](/developer-docs/api-reference/generate-token)), call the API by passing the token as a `Bearer` credential. For example, to start a CSV export of the identity inventory:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://devx.YOUR_TENANT.oleria.io/v1/downloads \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "context": "accessInventoryIdentitiesV2" }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://devx.YOUR_TENANT.oleria.io/v1/downloads",
      headers={
          "Authorization": f"Bearer {access_token}",
          "Content-Type": "application/json",
      },
      json={"context": "accessInventoryIdentitiesV2"},
  )
  download = resp.json()
  ```

  ```javascript Node.js theme={null}
  const res = await fetch("https://devx.YOUR_TENANT.oleria.io/v1/downloads", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${access_token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ context: "accessInventoryIdentitiesV2" }),
  });
  const download = await res.json();
  ```
</CodeGroup>

## Next steps

<Card title="Generate an API token" icon="key" href="/developer-docs/api-reference/generate-token">
  Walk through the OAuth 2.0 Client Credentials flow end-to-end, with troubleshooting and token-rotation guidance.
</Card>

The full endpoint reference - request schemas, response shapes, and copy-ready samples - is in the sidebar under each API group below.

## Contact us

For questions about the API, contact us at [support@oleria.com](mailto:support@oleria.com).