Authentication & Security

Creating API Keys

Navigate to Settings → API Keys → Create in the ARQERA app. Each key is shown exactly once at creation. Store it securely — you will not be able to view the full key again.

Authenticating Requests

Include your API key in the request header using either format:

Code Examples

curl -X GET https://api.arqera.io/api/diagnostic/health \
  -H "X-API-Key: ak_live_your_key_here"

import os
from arqera import ArqeraClient

client = ArqeraClient(
    api_key=os.environ["ARQERA_API_KEY"],
    base_url="https://api.arqera.io",
)

health = client.diagnostic.health()
print(health)

import { ArqeraClient } from '@arqera/sdk';

const client = new ArqeraClient({
  apiKey: process.env.ARQERA_API_KEY!,
  baseUrl: 'https://api.arqera.io',
});

const health = await client.diagnostic.health();
console.log(health);

API keys expire automatically after 90 days. A notification is sent 24 hours before deactivation. Follow this zero-downtime rotation process:

1. 1Create a new API key with the same scopes in Settings → API Keys.
2. 2Deploy the new key to your services. Both old and new keys work simultaneously.
3. 3Verify all services are using the new key by checking “Last Used” timestamps.
4. 4Revoke the old key. Revocation is immediate and irreversible.

Supported Identity Providers

SAML 2.0 Configuration

Provide these Service Provider (SP) details to your identity provider:

OpenID Connect Configuration

For OIDC-based SSO, configure the following in your identity provider:

When a user authenticates via SSO for the first time, ARQERA automatically creates their account and assigns them the Member role within your tenant. No manual user creation required. Name and email are synced from the identity provider on each login.

Token Details

Token Usage

// Login and receive tokens
const response = await fetch('https://api.arqera.io/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: '[email protected]',
    password: 'your-password',
  }),
});

const { access_token, refresh_token } = await response.json();

// Use access token for authenticated requests
const data = await fetch('https://api.arqera.io/api/governance/evaluations', {
  headers: { Authorization: `Bearer ${access_token}` },
});

// Refresh when access token expires
const refreshResponse = await fetch('https://api.arqera.io/auth/refresh', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ refresh_token }),
});

const { access_token: newAccessToken } = await refreshResponse.json();

Rate Limit Headers

Every API response includes rate limit headers so you can track your usage:

Handling 429 Responses

When rate limited, you receive a 429 Too Many Requests response. Implement exponential backoff with jitter:

async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) return response;

    if (attempt === maxRetries) {
      throw new Error('Rate limit exceeded after max retries');
    }

    const retryAfter = parseInt(response.headers.get('Retry-After') || '1');
    const jitter = Math.random() * 1000;
    const delay = retryAfter * 1000 * Math.pow(2, attempt) + jitter;

    await new Promise(resolve => setTimeout(resolve, delay));
  }
}