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. The secret is shown only when you create or rotate the key. If you lose it or suspect it has leaked, rotate the key immediately.

Get your client credentials

Generate OAuth client credentials from the Oleria web app. The client secret is shown once, on the create (or rotate) success screen. Copy it into your secret manager before you close that screen. You cannot retrieve it again from the key’s details.

Open Manage API Keys

Create an API key

Select Create API Key. Enter a descriptive name for your integration (for example, BI nightly export or internal access-graph viewer) and select Create.

Copy the client secret

The success screen shows your Client ID and Client secret. The secret is concealed until you select Reveal secret or Copy. Store both values in your secret manager before you select Done.

Please copy the client secret now. It will not be shown again. If you lose it, you must rotate or delete this API key.

Copy the remaining connection values

Open the new key from the list. The details panel shows the values you need besides the secret:

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. This matches the value from the create screen.

Use a separate API key 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 API Keys
Method	`POST`
Content-Type	`application/x-www-form-urlencoded`
Grant type	`client_credentials`

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, and client_secret.

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"

import os
import requests

resp = requests.post(
    "YOUR_AUTHENTICATION_URL",
    data={
        "grant_type": "client_credentials",
        "client_id": os.environ["OLERIA_CLIENT_ID"],
        "client_secret": os.environ["OLERIA_CLIENT_SECRET"],
    },
)
resp.raise_for_status()
token_payload = resp.json()
access_token = token_payload["access_token"]

const res = await fetch("YOUR_AUTHENTICATION_URL", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: process.env.OLERIA_CLIENT_ID,
    client_secret: process.env.OLERIA_CLIENT_SECRET,
  }),
});
if (!res.ok) throw new Error(`Token request failed: ${res.status}`);
const { access_token, expires_in } = await res.json();

package main

import (
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
    "strings"
)

func main() {
    form := url.Values{}
    form.Set("grant_type", "client_credentials")
    form.Set("client_id", os.Getenv("OLERIA_CLIENT_ID"))
    form.Set("client_secret", os.Getenv("OLERIA_CLIENT_SECRET"))

    req, _ := http.NewRequest("POST",
        "YOUR_AUTHENTICATION_URL",
        strings.NewReader(form.Encode()))
    req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

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 -X POST https://devx.YOUR_TENANT.oleria.io/v1/downloads \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "context": "accessInventoryIdentitiesV2" }'

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

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" }),
});

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

Rotating a key issues a new client_id and client_secret. The previous credentials stop working immediately.

Open the key

Go to Settings -> Manage API Keys and open the key you want to rotate.

Rotate credentials

Select Rotate credentials. Confirm the warning that both the client ID and client secret will change.

Copy the new values

Copy the new Client ID and Client secret from the success screen into your secret manager, then update every client that used the old credentials. The new secret is not shown again.

Rotate is an immediate cutover of the same key. To avoid dropped requests, create a second API key, roll the new client_id and client_secret out to every client, then delete the old key.

Troubleshooting

Symptom	Likely cause	Fix
`400 invalid_request` from the token endpoint	A required field (`grant_type`, `client_id`, or `client_secret`) 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 values in your secret manager. You cannot re-reveal the secret from the key details. If you have lost it, rotate the key and retry.
`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 support@oleria.com.

Getting Started

Inventory & Actions

Action jobs

TrustFusion

Downloads

Prerequisites

Get your client credentials

Token endpoint

Request a token

Use the token

Token lifetime and reuse

Rotate or revoke credentials

Troubleshooting

Contact us

​Prerequisites

​Get your client credentials

​Token endpoint

​Request a token

​Use the token

​Token lifetime and reuse

​Rotate or revoke credentials

​Troubleshooting

​Contact us

Prerequisites

Get your client credentials

Token endpoint

Request a token

Use the token

Token lifetime and reuse

Rotate or revoke credentials

Troubleshooting

Contact us