Authentication & Security

API Keys

API keys authenticate requests to Xerotier inference endpoints. Each key is a 256-bit cryptographically random value prefixed with xero_ followed by your project slug.

Key Format

Format

xero_<project_slug>_<random_token>

Using API Keys

Include the key in the Authorization header:

curl

                    curl -X POST https://api.xerotier.ai/proj_ABC123/my-endpoint/v1/chat/completions \
  -H "Authorization: Bearer xero_my-project_abc123" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama-3.1-8b", "messages": [{"role": "user", "content": "Hello"}]}'
                

Key Management

Operation	Description
Create	Generate a new API key from the project settings page. The full key is shown only once at creation time.
Rotate	Create a new key, update your applications, then revoke the old key. There is no in-place rotation -- you must create and swap.
Revoke	Permanently disable a key. Revoked keys cannot be re-enabled. Any requests using a revoked key receive a `401 Unauthorized` response.

Key Security

Store keys in environment variables or a secrets manager, never in source code.
Use separate keys for development, staging, and production environments.
Rotate keys regularly and immediately if you suspect a key has been compromised.
Monitor key usage in the dashboard to detect unauthorized access.

Client Examples

The following examples show how to authenticate with Xerotier using popular SDKs and HTTP clients. All examples use the OpenAI-compatible API format.

OpenAI SDK

Xerotier endpoints are OpenAI-compatible, so you can use the official OpenAI SDKs by pointing them at your Xerotier base URL.

Python

                    from openai import OpenAI

client = OpenAI(
    base_url="https://api.xerotier.ai/proj_ABC123/my-endpoint/v1",
    api_key="xero_my-project_abc123"
)

# All requests are automatically authenticated
response = client.chat.completions.create(
    model="my-model",
    messages=[{"role": "user", "content": "Hello"}]
)
                

Node.js

                    import OpenAI from "openai";

const client = new OpenAI({
    baseURL: "https://api.xerotier.ai/proj_ABC123/my-endpoint/v1",
    apiKey: "xero_my-project_abc123"
});

// All requests are automatically authenticated
const response = await client.chat.completions.create({
    model: "my-model",
    messages: [{ role: "user", content: "Hello" }]
});
                

Raw HTTP Requests

If you are not using an OpenAI SDK, include the API key in the Authorization header as a Bearer token.

Python (requests)

                    import requests

headers = {
    "Authorization": "Bearer xero_my-project_abc123",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.xerotier.ai/proj_ABC123/v1/models",
    headers=headers
)
                

Node.js (fetch)

                    const response = await fetch(
    "https://api.xerotier.ai/proj_ABC123/v1/models",
    {
        headers: {
            "Authorization": "Bearer xero_my-project_abc123"
        }
    }
);
const data = await response.json();
                

OAuth & SSO

Xerotier supports two independent OAuth providers for dashboard login: GitHub OAuth and Auth0 SSO. These are for user authentication to the web dashboard, not for API access (which always uses API keys).

GitHub OAuth

GitHub OAuth allows users to sign in to the Xerotier dashboard using their GitHub account. When configured, a "Sign in with GitHub" button appears on the login page.

Step	Description
1. Initiate	User clicks "Sign in with GitHub" which redirects to `/auth/github`.
2. Authorize	GitHub prompts the user to authorize the Xerotier application.
3. Callback	GitHub redirects to `/auth/github/callback` with an authorization code.
4. Session	Xerotier exchanges the code for user information, creates or links the account, and establishes a session.

If a Xerotier account already exists with the same email address, the GitHub identity is linked to that existing account. Users can unlink their GitHub account from the account settings page.

Auth0 SSO

Auth0 provides enterprise single sign-on integration. When enabled, Auth0 handles authentication and can connect to your organization's identity provider (Active Directory, Okta, SAML, etc.).

When Auth0 SSO is configured for your deployment, a "Sign in with SSO" button appears on the login page. The login flow is similar to GitHub OAuth: click the button, authenticate with your identity provider, and you are redirected back to Xerotier with an active session.

Auth0 and GitHub OAuth are independent providers. When both are enabled, users see sign-in buttons for each provider on the login page.

Two-Factor Authentication (2FA)

Xerotier supports TOTP-based two-factor authentication for an additional layer of account security. When enabled, login requires both your password and a time-based code from an authenticator app.

Supported Authenticator Apps

Any TOTP-compatible authenticator app works, including Google Authenticator, Authy, 1Password, Bitwarden, and Microsoft Authenticator.

Setup Process

Navigate to Account Settings and select Security.
Click "Enable Two-Factor Authentication".
Scan the QR code with your authenticator app (or enter the secret manually).
Enter the 6-digit code from your authenticator to verify setup.
Save your backup codes in a secure location (see Backup Codes).

Login with 2FA

After entering your password, you are prompted for a 6-digit TOTP code. You have 5 minutes to enter the code before the verification window expires and you must start the login process again.

Disabling 2FA

You can disable 2FA from Account Settings. You must provide a valid TOTP code to confirm the change. Disabling 2FA removes the TOTP secret and invalidates all backup codes.

Security Details

TOTP secrets are encrypted at rest.
Rate limiting is applied to 2FA verification attempts to prevent brute-force attacks.

Backup Codes

When you enable 2FA, Xerotier generates a set of one-time backup codes. These codes allow you to regain access to your account if you lose your authenticator device.

Using Backup Codes

Each backup code can only be used once.
Enter a backup code in place of the TOTP code during login.
After using a backup code, it is permanently consumed.

Storage Guidance

Save backup codes immediately after generation -- they are shown only once.
Store them in a secure location separate from your authenticator device (e.g., a password manager, printed copy in a safe).
Do not store backup codes alongside your regular password.

Regenerating Backup Codes

You can regenerate backup codes from Account Settings. Regenerating creates a new set and invalidates all previous codes. You must provide a valid TOTP code to regenerate.

Account Recovery

If you have lost both your authenticator device and all backup codes, you can request account recovery. The recovery process requires email verification and may take additional time for security review.

Sessions & Cookies

The Xerotier dashboard uses cookie-based session management. Sessions are created at login and extended on activity.

Behavior	Details
Session extension	Each activity extends the session by 60 minutes.
Maximum lifetime	Sessions expire after 8 hours regardless of activity.
Password change	Changing your password invalidates all active sessions.

Session cookies are marked Secure and HttpOnly, requiring HTTPS. Changing your password or an admin resetting your password invalidates all active sessions.

CSRF Protection

All state-changing requests to the Xerotier dashboard require a CSRF token. The token is embedded in a <meta> tag on each page and must be sent as the X-CSRF-Token header on POST, PUT, PATCH, and DELETE requests.

For Custom Frontend Integrations

If you build custom JavaScript that calls Xerotier dashboard APIs (not the inference API), extract the CSRF token from the meta tag:

JavaScript

                    const token = document.querySelector('meta[name="csrf-token"]').content;
fetch('/api/some-action', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CSRF-Token': token
  },
  body: JSON.stringify({...})
});
                

CSRF protection applies only to the web dashboard. The inference API uses API key authentication and does not require CSRF tokens.

Security Best Practices

API Key Security

Never commit API keys to version control.
Use environment variables or a secrets manager (HashiCorp Vault, AWS Secrets Manager, etc.).
Create separate keys per application or environment.
Rotate keys on a regular schedule (monthly or quarterly).
Revoke keys immediately if compromised.

Account Security

Enable two-factor authentication for all user accounts.
Use strong, unique passwords (minimum 12 characters).
Store backup codes in a secure, offline location.
Review active sessions periodically in Account Settings.

Network Security

Always use HTTPS for API calls. HTTP requests are rejected in production.
The dashboard sets Strict-Transport-Security (HSTS) headers in production mode.
Session cookies are marked Secure and HttpOnly by default.

If a Key Is Compromised

Revoke the compromised key immediately from the dashboard.
Create a new replacement key.
Update all applications using the old key.
Review recent usage logs for unauthorized access.
If your account may be compromised, change your password (this invalidates all sessions) and regenerate backup codes.