Generate an API Token

Mint a short-lived access token using OAuth 2.0 Client Credentials, and use it to authenticate calls to the Oleria API. The Oleria API uses the OAuth 2.0 Client Credentials grant: you exchange a client_id and client_secret for a short-lived JWT access token, then pass that token as a Bearer credential on every API call.

Prerequisites

• Network access from your client to the Oleria authorization server and to the Oleria API base URL for your environment.
• A secret manager or environment-variable store to hold the client_secret outside of source control.

Treat your client_secret like a password. Never commit it to source control, paste it into chat or tickets, or embed it in client-side code. If you suspect a secret has leaked, rotate it immediately by deleting the key from Settings → Manage APIs and creating a new one.

Get your client credentials

Generate OAuth client credentials directly from the Oleria web app:

1. Sign in to your Oleria workspace and open Settings → Manage APIs.
2. Click Create OAuth application in the top right.
3. Enter a descriptive name for your integration (for example, BI nightly export or internal access-graph viewer) and click Create.
4. The new application opens in a side panel with the values you need to call the API:
   • API URL - the base URL for your API calls.
   • Authentication URL - the OAuth token endpoint for your tenant.
   • Audience - the OAuth audience to use when requesting a token.
   • Client ID - your application’s identifier.
   • Client secret - shown masked; use the eye icon to reveal it or the copy icon to copy it to your clipboard.
5. Copy the client_id, client_secret, and Authentication URL into your secret manager. Treat the secret like a password.

Use a separate OAuth application for each integration. This makes auditing easier and limits the blast radius if any single credential is compromised.

Token endpoint

Field	Value
URL	Your Authentication URL from Settings → Manage APIs
Method	POST
Content-Type	application/x-www-form-urlencoded
Grant type	client_credentials
Scope	ClientCredentialsResourceServer/client_credentials_base_scope

The token endpoint URL is tenant-specific and is shown in the Authentication URL field when you create an API key.

Request a token

Send a form-encoded POST to the token endpoint. The body must include grant_type, client_id, client_secret, and scope.

cURL

curl -X POST YOUR_AUTHENTICATION_URL \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=ClientCredentialsResourceServer/client_credentials_base_scope"

A successful call returns 200 OK with a JSON body:

{
  "access_token": "eyJraWQiOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Field	Description
access_token	The JWT to send on subsequent API calls.
token_type	Always Bearer.
expires_in	Lifetime of the token in seconds (typically 3600, i.e. one hour).

Use the token

Send the token as a Bearer credential in the Authorization header on every Oleria API request.

cURL

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

Token lifetime and reuse

• A token is valid for expires_in seconds (typically one hour).
• Reuse the same token for every API call until it is close to expiry. Minting a new token for every request is wasteful and can hit auth-side rate limits.
• Cache tokens in memory inside your client and refresh them when they have fewer than 60 seconds of life remaining.
• Treat access tokens like passwords - keep them in memory only, and avoid writing them to disk or logs.

If you use a standard OAuth 2.0 client library (for example, requests-oauthlib in Python or golang.org/x/oauth2/clientcredentials in Go), token caching and automatic refresh are handled for you.

Rotate or revoke credentials

To rotate a client_secret, delete the API key from Settings → Manage APIs and create a new one. Roll out the new client_id and client_secret to every client that uses them before deleting the old key. Plan rotations during a low-traffic window to avoid dropped requests.

Troubleshooting

Symptom	Likely cause	Fix
400 invalid_request from the token endpoint	A required field (grant_type, client_id, client_secret, or scope) is missing or misspelled.	Compare your request body to the Request a token sample.
401 invalid_client from the token endpoint	The client_id or client_secret is wrong, or the credentials are not active in this environment.	Confirm the credentials with Customer Success and verify you are calling the right environment.
401 Unauthorized from an API endpoint after a successful token call	The token has expired, or the Authorization header is malformed.	Mint a fresh token and ensure the header is exactly Authorization: Bearer <token>.
403 Forbidden from an API endpoint	The token is valid but the credential is not scoped for that resource.	Contact Customer Success to confirm the credential has the right permissions.
Token request hangs or times out	Network egress to your Authentication URL host is blocked.	Allow-list the hostname from your Authentication URL and your API URL in your egress firewall.

Contact us

For questions about API authentication, contact us at [e-mail].