Skip to main content

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.

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​

Create keys in the portal 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)​

The Auth API 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​

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.