API Authentication

Secure access to the Olimi API is crucial for protecting your data and ensuring the integrity of your communications. This guide walks you through the authentication process for the Olimi external API.

Authentication Method

Olimi’s external API uses a static API key sent in a request header. There is no token-exchange step — you include the same key on every request.


Scheme	API key in header
Header name	`X-API-KEY`
Header value	Your raw API key
Base URL	`{{base_url}}/api/v2`

Obtaining an API Key

API keys are provisioned for your company by the Olimi team and can be managed from the Dashboard. Each key is tied to a single company and remains valid until it is deactivated. There is no self-service generate-token endpoint — you do not exchange credentials for a short-lived bearer token. The API key itself is what you send on every request.

Using the API Key

Include your API key in the X-API-KEY header of every request to /api/v2/*.

Example using cURL

curl -H "X-API-KEY: YOUR_API_KEY" \
     https://api-eg.olimi.ai/api/v2/customer-lists

Example using JavaScript (fetch)

fetch('https://api-eg.olimi.ai/api/v2/customer-lists', {
  headers: {
    'X-API-KEY': 'YOUR_API_KEY'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

Example using Python (requests)

import requests

response = requests.get(
    'https://api-eg.olimi.ai/api/v2/customer-lists',
    headers={'X-API-KEY': 'YOUR_API_KEY'}
)
print(response.json())

Do not use the Authorization: Bearer ... header when authenticating with API keys. The endpoints validate API keys sent directly in the X-API-KEY header; Bearer tokens are reserved for JWT-based user session authentication.

Best Practices

To keep your Olimi account and data secure:

Keep your API key secret. Never share it publicly or commit it to version control.
Use environment variables. Store the key in environment variables or a secrets manager rather than hardcoding it.
Rotate keys periodically. Ask the Olimi team to issue a new key and deactivate the old one.
Use HTTPS only. Never send the key over plain HTTP.
Server-side only. The API key grants full access to your company’s external API surface — never ship it in client-side JavaScript, mobile apps, or any context a user can inspect.

Error Handling

If authentication fails, the API responds with HTTP 401 Unauthorized and a JSON body:

{
  "success": false,
  "message": "🚨 Nice try, but no cigar."
}

Common reasons for a 401 here:

The X-API-KEY header is missing.
The key value does not match any record in the database.
The key exists but is no longer linked to a company (e.g. the company has been removed).

Always check for and handle authentication errors in your integration.

Support

If you run into issues with authentication or need a new API key issued, contact our support team at [email protected]. Remember: your API key is the credential for your Olimi account’s external API access. Keep it confidential and secure at all times.

Getting Started

API Overview

Agents & Campaigns

Speech

API Authentication

Authentication Method

Obtaining an API Key

Using the API Key

Example using cURL

Example using JavaScript (fetch)

Example using Python (requests)

Best Practices

Error Handling

Support

​Authentication Method

​Obtaining an API Key

​Using the API Key

​Example using cURL

​Example using JavaScript (fetch)

​Example using Python (requests)

​Best Practices

​Error Handling

​Support

Authentication Method

Obtaining an API Key

Using the API Key

Example using cURL

Example using JavaScript (fetch)

Example using Python (requests)

Best Practices

Error Handling

Support