Authentication

JWT Authentication

For user sessions, authenticate with a Supabase JWT:

curl https://arke-v1.arke.institute/entities \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

The gateway validates the JWT and sets trusted headers (X-User-Id, X-User-Email) on downstream requests. No additional setup is needed -- your Supabase token works directly.

API Key Authentication

For agents and services, use an API key:

curl https://arke-v1.arke.institute/entities \
  -H "Authorization: ApiKey ak_xxxxx"

API keys are created through the agent management system and are scoped to specific agent entities.

Network Selection

Set the X-Arke-Network header to choose between production and test:

# Production (default)
curl https://arke-v1.arke.institute/entities

# Test network
curl https://arke-v1.arke.institute/entities \
  -H "X-Arke-Network: test"

Test network entities use II-prefixed IDs and route to separate storage.

On-Behalf-Of

Service accounts can act on behalf of specific users:

curl https://arke-v1.arke.institute/entities \
  -H "Authorization: Bearer service-jwt" \
  -H "X-On-Behalf-Of: 01JUSER..."

This scopes the request to the specified user's permissions while recording both the service and user in the audit trail.

Error Responses