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

# Authentication

> How to authenticate with the Grantiva API

Different API endpoints use different authentication methods depending on the caller.

## SDK / Mobile app

The iOS SDK identifies your app with **Bundle ID + Team ID** headers:

```
X-Bundle-ID: com.yourapp.example
X-Team-ID: ABBM6U9RM5
```

These headers are sent automatically by the SDK — but they only *identify* the tenant, they are not authentication. Bundle IDs and Team IDs are discoverable from the App Store, so they are not secrets.

**Attestation endpoints** (`/challenge`, `/validate`, `/refresh`) need only these headers — the attestation object itself is the proof.

**All other SDK endpoints** — feature flags, the flag SSE stream, heartbeat, feedback, and support — additionally require one of:

* **A Grantiva JWT** issued by attestation, sent as `Authorization: Bearer <jwt>` (this is what the SDK does automatically after `validateAttestation()`), or
* **An API key** (simulator/development mode, or server-side callers).

Requests with only the identity headers receive `401 Unauthorized` with `WWW-Authenticate: Bearer realm="grantiva"`.

<Note>
  In practice the SDK handles this for you: run `validateAttestation()` once before using flags, feedback, or support. In the iOS Simulator (no App Attest), initialize the SDK with an API key instead — see [Simulator Setup](/simulator-setup).
</Note>

## Server-to-server

For backend integrations (analytics, VRT CLI), use an **API key**:

```bash theme={null}
# Header style
curl -H "X-API-Key: aat_your_api_key" https://api.grantiva.io/api/v1/analytics/dashboard

# Or Bearer style
curl -H "Authorization: Bearer aat_your_api_key" https://api.grantiva.io/api/v1/analytics/dashboard
```

API keys are created in the dashboard under **Settings**.

| Prefix      | Type                 |
| ----------- | -------------------- |
| `aat_`      | Organization API key |
| `gpat_`     | Personal API key     |
| `grantiva_` | Legacy key format    |

## JWT token

After successful attestation, the SDK receives a JWT token. Protected endpoints require this token:

```bash theme={null}
curl -H "Authorization: Bearer eyJhbGciOi..." https://api.grantiva.io/api/v1/heartbeat
```

## Admin API

For internal admin operations:

```bash theme={null}
curl -H "X-Admin-API-Key: your_admin_key" https://api.grantiva.io/admin/v1/tenants
# Or
curl -H "Authorization: Admin your_admin_key" https://api.grantiva.io/admin/v1/tenants
```

## Summary

| Endpoint group                           | Auth method                                       | Who uses it                |
| ---------------------------------------- | ------------------------------------------------- | -------------------------- |
| Attestation (challenge/validate/refresh) | Bundle ID + Team ID headers + attestation object  | iOS SDK                    |
| Flags, Feedback, Support, Heartbeat      | Identity headers **+** attestation JWT or API key | iOS SDK (post-attestation) |
| Analytics, VRT                           | API key                                           | Your backend, CLI          |
| Admin                                    | Admin API key                                     | Internal tooling           |