# Authentication

The Edge API accepts two kinds of credentials. Programmatic integrations use a tenant API key. Browser sessions and user-facing tools use a JWT issued by the Auth API.

## API keys (recommended for integrations)[​](#api-keys-recommended-for-integrations "Direct link to API keys (recommended for integrations)")

Tenant API keys are prefixed `rgl_tenant_`. Send the key in the `X-Api-Key` header:

```
curl https://api.merrows.ai/api/tenants/{tenantSlug}/conversations \

  -H "X-Api-Key: rgl_tenant_your_key_here"
```

API keys never go in the Authorization header

`Authorization: Bearer ...` is reserved for JWTs. Sending an API key as a Bearer token returns 401. Always use the `X-Api-Key` header for API keys.

### Creating a key[​](#creating-a-key "Direct link to Creating a key")

Create keys in the [portal](https://portal.merrows.ai) under your tenant's settings, or with an existing credential:

```
curl -X POST https://api.merrows.ai/api/tenants/{tenantSlug}/api-keys \

  -H "X-Api-Key: rgl_tenant_existing_key" \

  -H "Content-Type: application/json" \

  -d '{"name": "my-integration"}'
```

The raw key is returned once at creation and stored hashed. If you lose it, revoke it and create a new one.

A tenant key is scoped to its tenant. Requests against another tenant's resources return 403.

## JWT bearer tokens (user sessions)[​](#jwt-bearer-tokens-user-sessions "Direct link to JWT bearer tokens (user sessions)")

The [Auth API](/api/auth/merrows-auth-api.md) issues JWTs on login:

```
curl -X POST https://auth.merrows.ai/api/v1/auth/login \

  -H "Content-Type: application/json" \

  -d '{"email": "you@example.com", "password": "..."}'
```

Send the resulting token on Edge API calls:

```
curl https://api.merrows.ai/api/tenants/{tenantSlug}/conversations \

  -H "Authorization: Bearer eyJhbGciOi..."
```

Access tokens are short-lived. Use `POST /auth/refresh` with the refresh token to get a new one. Browsers on `*.merrows.ai` get the same JWT in an HttpOnly cookie at login, so requests from the Merrows subdomains authenticate automatically with `credentials: 'include'`.

## Permissions[​](#permissions "Direct link to Permissions")

What a credential can do depends on its tenant role. Endpoints in this reference are annotated with the operations they allow. Endpoints for platform administration are not part of this public reference; they require a global admin session and are documented separately under [Internal API](/internal-api).