> ## Documentation Index
> Fetch the complete documentation index at: https://lifters.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://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:

```bash theme={null}
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

<Warning>
  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)
</Warning>

**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

```bash theme={null}
# Login
curl -X POST https://api.atlas.io/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "password": "your_password"
  }'
```

Response:

```json theme={null}
{
  "data": {
    "token": "eyJhbGciOiJSUzI1NiJ9...",
    "expires_at": "2026-03-11T22:30:00Z",
    "user": {
      "id": "user_abc123",
      "email": "your@email.com"
    }
  }
}
```

### Use the JWT Token

```bash theme={null}
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:

```bash theme={null}
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](https://app.atlas.io/login)
2. Click **Continue with Google**
3. Complete Google's authentication flow
4. You'll be redirected to the Dashboard

<Note>
  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.
</Note>

***

## 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                     |