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 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), call the API by passing the token as a Bearer credential. For example, to start a CSV export of the identity inventory:

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" }'

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

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

Next steps

Generate an API token

Walk through the OAuth 2.0 Client Credentials flow end-to-end, with troubleshooting and token-rotation guidance.

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.

Getting Started

Inventory & Actions

Action jobs

TrustFusion

Downloads

Environments

Authentication

Conventions

Errors

Rate limits

Example request

Next steps

Generate an API token

Contact us

​Environments

​Authentication

​Conventions

​Errors

​Rate limits

​Example request

​Next steps

Generate an API token

​Contact us

Environments

Authentication

Conventions

Errors

Rate limits

Example request

Next steps

Contact us