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

# Authentication

> API key types, permissions, and authentication headers

## Base URLs

All API requests are made to one of the following base URLs depending on your environment:

| Environment | Base URL                |
| ----------- | ----------------------- |
| Production  | `https://api.appdna.ai` |
| Sandbox     | `https://api.appdna.ai` |

<Warning>
  Both environments share the same base URL, `https://api.appdna.ai` — the API-key prefix (`adn_test_` vs `adn_live_`) selects sandbox vs production. Never use production API keys in sandbox or development environments. Use test keys during development.
</Warning>

***

## API Key Types

AppDNA uses two distinct key types, each designed for a different integration surface.

### 1. SDK API Keys

SDK API Keys authenticate mobile SDKs (iOS, Android, Flutter, React Native) against the ingestion and config-bundle endpoints.

| Field             | Description                                                                          |
| ----------------- | ------------------------------------------------------------------------------------ |
| `public_key`      | Unique public identifier, prefixed `adn_live_` (production) or `adn_test_` (sandbox) |
| `secret_key_hash` | Hashed secret counterpart                                                            |
| `environment`     | `production` or `sandbox`                                                            |
| `status`          | `active` or `revoked`                                                                |

Send the public key in the `x-api-key` header:

```bash theme={null}
curl -X POST https://api.appdna.ai/api/v1/ingest/events \
  -H "Content-Type: application/json" \
  -H "x-api-key: adn_live_a1b2c3d4e5f6" \
  -d '{ ... }'
```

### 2. Dashboard Session Tokens

Dashboard and analytics endpoints (analytics, webhooks, settings, etc.) are authenticated with the Firebase session token of the signed-in console user — **not** a standalone REST API key. Send the Firebase ID token as a Bearer token along with headers identifying the organization and application in scope:

```bash theme={null}
curl https://api.appdna.ai/api/v1/analytics/kpis \
  -H "Authorization: Bearer <firebase-id-token>" \
  -H "x-tenant-id: <organization-id>" \
  -H "x-app-id: <application-id>" \
  -H "Content-Type: application/json"
```

The server verifies the Firebase token and resolves it to the caller's user, organization, and role. Access to the requested organization and application is enforced against the caller's memberships.

***

## Authentication Levels

AppDNA enforces four authentication levels depending on the endpoint:

### Public

No authentication required. Used for health checks and public endpoints.

| Endpoint                          | Purpose                    |
| --------------------------------- | -------------------------- |
| `GET /api/v1/ingest/health`       | Ingestion health check     |
| `GET /api/v1/auth/signup-enabled` | Check if signup is enabled |
| `POST /api/v1/auth/login`         | User login                 |
| `POST /api/v1/auth/signup`        | User registration          |

### SDK Key

Requires the `x-api-key` header. Resolves the key to an `app_id` and `tenant_id` pair. Used by the mobile SDKs.

| Endpoint                                | Purpose                |
| --------------------------------------- | ---------------------- |
| `GET /api/v1/sdk/bootstrap`             | SDK bootstrap          |
| `POST /api/v1/ingest/events`            | Event ingestion        |
| `GET /api/v1/sdk/config-bundle`         | Download config bundle |
| `GET /api/v1/sdk/config-bundle/version` | Check bundle version   |

### Customer (JWT)

Requires a valid Firebase session token plus `x-tenant-id` and `x-app-id` headers. The server resolves the caller to:

```typescript theme={null}
{
  tenantId: string;   // Organization ID
  appId: string;      // Application ID
  userId: string;     // Authenticated user ID
  role: 'owner' | 'admin' | 'member' | 'viewer';
}
```

Used by all dashboard API endpoints (analytics, webhooks, settings, etc.).

### Super Admin

Requires a valid session token carrying the super-admin claim, which the server verifies before granting access. Used exclusively for platform-operator endpoints (tenant management, platform billing, etc.).

<Info>
  Super Admin endpoints are not available to regular API consumers. They are reserved for platform operators.
</Info>

***

## Managing API Keys

API keys are managed from the AppDNA Console:

1. Navigate to **Settings** in the left sidebar
2. Select the **SDK** tab
3. Click **API Keys**
4. Use **Create Key** to generate a new key pair

<Note>
  When you create a new SDK API Key, the secret key is shown only once. Store it securely -- you will not be able to retrieve it again.
</Note>

### Rotating Keys

To rotate an SDK API Key:

```bash theme={null}
POST /api/v1/sdk/api-keys/{id}/rotate
```

This generates a new key and invalidates the previous one. Allow a brief overlap period in your deployment to avoid downtime.

***

## Rate Limits

Rate limits are configurable per application from your app's settings.

| Setting           | Default      | Description                                          |
| ----------------- | ------------ | ---------------------------------------------------- |
| Events per minute | Configurable | Maximum number of events accepted per minute per app |

When the rate limit is exceeded, the API responds with HTTP `429 Too Many Requests`. The SDK automatically retries with exponential backoff.

<Check>
  You have successfully configured authentication when your SDK can call the bootstrap endpoint and receive a valid response with your `orgId` and `appId`.
</Check>