Authentication

How to authenticate with the Atlas APIs — API Keys for the Events API, JWT tokens for the Backend API.

Authentication Methods

Atlas uses two authentication mechanisms depending on which API you’re calling:

API	Method	Header
Events API (domain endpoints)	API Key	X-API-Key
Events API (generic endpoints)	JWT Bearer	Authorization: Bearer <token>
Backend API	JWT Bearer	Authorization: Bearer <token>
Dashboard	Auth0 (email/password or Google)	— (session-based)

---

API Key Authentication

Used for all domain event endpoints: /api/v1/user, /api/v1/transaction, /api/v1/casino, /api/v1/sport.

Get Your API Key

1. Log in to app.atlas.io
2. Navigate to Settings → API Keys
3. Click Create API Key
4. Name it (e.g., Production - Events) and select the brand
5. Copy the key — it is only shown once

Use the API Key

Pass the key in the X-API-Key header on every request:

curl -X POST https://events.atlas.io/api/v1/casino \
  -H "X-API-Key: atl_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

API Key Best Practices

Treat API keys like passwords. Never:

• Commit them to version control
• Log them in application logs
• Expose them in client-side JavaScript
• Share them across multiple environments (use separate keys per env)

Do:

• Store in environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault)
• Create separate keys for staging and production
• Rotate keys periodically (every 90 days recommended)
• Delete unused keys immediately

API Key Rotation

1. Create a new key in Dashboard → Settings → API Keys
2. Deploy your new key to your environment
3. Verify events are flowing with the new key
4. Delete the old key

Zero-downtime rotation: both keys work simultaneously until the old one is deleted.

---

JWT Bearer Authentication

Used for the generic events endpoint (/v1/events) and all Backend API calls.

Obtaining a Token

# Login
curl -X POST https://api.atlas.io/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "your_password"
  }'

Response:

{
  "data": {
    "token": "eyJhbGciOiJSUzI1NiJ9...",
    "expires_at": "2026-03-11T22:30:00Z",
    "user": {
      "id": "user_abc123",
      "email": "[e-mail]"
    }
  }
}

Use the JWT Token

curl -X POST https://events.atlas.io/v1/events \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Token Lifecycle

Property	Value
Algorithm	RS256 (signed by Auth0)
Default TTL	24 hours
Refresh	Re-authenticate via /auth/login
Validation	Public key from Auth0 JWKS endpoint

---

Multi-Organization Context

If your user account belongs to multiple organizations, you must select the active organization after login:

curl -X POST https://api.atlas.io/auth/select-organization \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_abc123"
  }'

This returns a new token scoped to that organization. All subsequent requests should use this organization-scoped token.

---

Google OAuth

Atlas supports Google login for dashboard access:

1. Navigate to app.atlas.io/login
2. Click Continue with Google
3. Complete Google’s authentication flow
4. You’ll be redirected to the Dashboard

Google accounts and email/password accounts with the same email address are automatically linked to the same Atlas user. You can use either method to log in.

---

Error Responses

Status	Code	Meaning
401	UNAUTHORIZED	Missing, expired, or invalid token/key
403	FORBIDDEN	Valid token but insufficient permissions for this resource
429	RATE_LIMITED	Too many requests — back off and retry