Authentication

Arke supports three authentication methods, each suited to different use cases.

JWT Authentication

For browser-based user sessions, authenticate with a Supabase JWT:

curl https://api.arke.institute/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

The gateway validates the JWT and extracts user identity. Your Supabase token works directly with no additional setup.

Registration

New users must register before making authenticated requests. Registration creates a user entity from your JWT claims:

curl -X POST https://api.arke.institute/auth/register \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response:

{
  "created": true,
  "user": {
    "id": "01JUSER123...",
    "cid": "bafyrei...",
    "properties": { "label": "Alice Smith" },
    "ver": 1
  }
}

Registration is idempotent -- calling it again returns the existing user with "created": false.

User API Keys (uk_)

For programmatic access (SDKs, CLIs, CI/CD), create a user API key. These authenticate as you with the same permissions.

Create a Key

curl -X POST https://api.arke.institute/users/me/keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"label": "CLI key", "expires_in": 7776000}'

Response:

{
  "key": "uk_a1b2c3d4e5f6...",
  "key_prefix": "uk_a1b2c",
  "expires_at": "2025-04-01T00:00:00.000Z"
}

Important: The full key is only returned once. Store it securely.

Use the Key

curl https://api.arke.institute/users/me \
  -H "Authorization: ApiKey uk_a1b2c3d4e5f6..."

List Keys

curl https://api.arke.institute/users/me/keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Returns key prefixes (not full keys), labels, and usage timestamps.

Revoke a Key

curl -X DELETE https://api.arke.institute/users/me/keys/uk_a1b2c \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Revocation is immediate. The key becomes invalid for all future requests.

Key Properties

Agent API Keys (ak_)

Agents are external services that process entities. They authenticate with agent API keys, which authenticate as the agent (not a user).

curl https://api.arke.institute/entities/01JFILE... \
  -H "Authorization: ApiKey ak_x9y8z7w6v5u4..."

Agent keys are managed via /agents/{id}/api-keys endpoints. See the Agents documentation for details.

Key Differences from User Keys

Network Selection

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

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

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

Test network entities use II-prefixed IDs and route to separate storage. This is useful for development and testing without affecting production data.

On-Behalf-Of (Service Accounts)

Service accounts can act on behalf of specific users:

curl https://api.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.

Without the X-On-Behalf-Of header, service accounts operate in system mode with elevated permissions.

Error Responses

Common 403 Scenarios

• "User not registered" -- Call POST /auth/register first
• "Action not allowed" -- You don't have permission for this operation
• "Only users can..." -- Some operations require user auth, not agent auth

SDK Usage

The Arke SDK handles authentication automatically:

import { ArkeClient } from '@arke-institute/sdk';

// With user API key
const arke = new ArkeClient({
  apiKey: 'uk_a1b2c3d4e5f6...',
});

// With JWT (browser)
const arke = new ArkeClient({
  accessToken: supabaseSession.access_token,
});

// Get current user
const me = await arke.users.me();

See the SDK documentation for more details.