Authenta's API uses a bearer token authentication mechanism.
Every request must include your API Key in the Authorization header.

This page explains how to authenticate with the API and how authentication-related errors are returned.

How Authentication Works

Every API request must include:

• Authorization header – Bearer token format with your API key

Your API key is generated when you create an API key in your console and acts as your authentication credential.

Required Authentication Header

All API requests must include the following header:

Authorization: Bearer api_xxxxxxxx...

Example request:

GET /api/v1/jobs HTTP/1.1
Host: platform.authenta.ai
Authorization: Bearer api_xxxxxxxx...

Example in cURL

curl -X GET "https://platform.authenta.ai/api/v1/jobs" \
  -H "Authorization: Bearer api_xxxxxxxx..."

Example in JavaScript (Node.js)

const res = await fetch('https://platform.authenta.ai/api/v1/jobs', {
  headers: {
    'Authorization': `Bearer ${process.env.AUTHENTA_API_KEY}`,
  },
});
 
const body = await res.json();
console.log(body);

Example in Python

import requests
 
headers = {
    "Authorization": f"Bearer {API_KEY}"
}
 
response = requests.get("https://platform.authenta.ai/api/v1/jobs", headers=headers)
print(response.json())

Authenta uses a structured error format containing:

• code — unique error identifier
• statusCode — HTTP status code
• message — human-readable explanation

Below are the authentication-related error codes your API may return.

❌ INVALID_API_KEY — Invalid or Missing API Key

Returned when the API key is missing, invalid, revoked, or malformed.

Example Response

{
  "code": "INVALID_API_KEY",
  "statusCode": 401,
  "message": "API key authentication failed"
}

❌ FORBIDDEN — Missing Required Permissions

Returned when the key is valid but does not have the required permission (e.g., a key with only READ permission attempts a DELETE or POST).

Example Response

{
  "code": "FORBIDDEN",
  "statusCode": 403,
  "message": "You don't have permission to access this"
}

❌ INSUFFICIENT_BALANCE — Insufficient Credit Balance

Returned when your account does not have enough credits to perform the requested operation.

Example Response

{
  "code": "INSUFFICIENT_BALANCE",
  "statusCode": 402,
  "message": "Insufficient balance. Please top up or enable pay-as-you-go billing"
}

When the API receives a request, it performs the following checks in order:

1. Validate Authorization header
2. Validate API key format
3. Check permissions (Read / Write / Delete)
4. Check credit balance (for media processing)

Depending on which check fails, the appropriate error code is returned.

🔒 1. Keep your API Key private

Store it using environment variables or secret managers. Never hard-code it into your source code.

🔑 2. Use separate keys for separate environments

Production, staging, CI, automation, etc.

🔄 3. Rotate keys periodically

You can regenerate your API key anytime for enhanced security.

📉 4. Monitor usage & credit balance

Track your credit usage to avoid running out of credits mid-operation.

Once authentication is set up:

• Learn how to use the API
• View how quotas & credits work
• Explore the Jobs API Reference