Permissions & Collections
How authentication and authorization work in Arke -- JWT auth, API keys, collections, roles, and permission actions.
Authentication
Arke supports two authentication methods:
JWT (JSON Web Tokens)
Users authenticate through Supabase. The gateway validates the JWT and sets trusted headers on downstream requests:
| Header | Description |
|---|---|
X-User-Id | Internal user entity ID |
X-User-Email | User's email address |
X-User-Role | service for service accounts |
API Keys
Agents and external services authenticate with API keys:
Authorization: ApiKey ak_xxxxxAPI keys are scoped to specific agents and grant the permissions defined in the agent's configuration.
Collections as Permission Boundaries
Every entity belongs to at least one collection. Collections are the permission boundary -- a user's role in a collection determines what they can do with entities inside it.
Roles
| Role | Can View | Can Edit | Can Create | Can Delete | Can Manage |
|---|---|---|---|---|---|
viewer | Yes | No | No | No | No |
editor | Yes | Yes | Yes | No | No |
admin | Yes | Yes | Yes | Yes | Partial |
owner | Yes | Yes | Yes | Yes | Yes |
Permission Actions
Actions follow the resource:verb pattern:
| Action | Description |
|---|---|
entity:view | Read entity content |
entity:edit | Modify existing entity |
entity:create | Create new entities |
entity:delete | Soft-delete entity |
collection:manage | Manage roles and membership |
file:download | Access original file binary |
Wildcard actions like *:view match any resource type.
Service Accounts
Service accounts are long-lived credentials for internal services. They operate in two modes:
On-Behalf-Of mode -- The service acts as a specific user, inheriting that user's permissions:
X-User-Role: service
X-On-Behalf-Of: user123System mode -- The service operates with full system access, bypassing permission checks:
X-User-Role: service
(no X-On-Behalf-Of header)Agent Authorization
Agents authenticate with API keys and operate within scoped permissions. Key features:
- Temporal permissions -- Access grants that auto-expire after a set duration
- Per-agent scoping -- Each agent declares what permissions it needs
- Request signing -- Arke signs outbound requests to agents with Ed25519 (
X-Arke-Signatureheader) - Audit trail -- Every action records both the agent and the original user in
edited_by