Authentication

Operator Authentication

ASN uses magic link authentication via Clerk. When you sign in, you receive an email with a one-time link. Click it, and you are authenticated. No passwords.

Operator sessions are used for dashboard access and account management. They return a session token used in the Authorization header.

Authorization: Bearer YOUR_SESSION_TOKEN

Sessions expire automatically. The session table tracks IP address, user agent, and expiration time for security auditing.

API Keys

For programmatic access — reporting activity, querying agents, running integrations — use API keys. Keys are scoped to your operator account or a specific platform.

Creating a Key

POST /api/v1/operators/me/api-keys

{
  "name": "Production Key",
  "permissions": ["read", "write", "activity:report"]
}

Response includes the full key exactly once:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production Key",
  "key": "asn_live_k1a2b3c4d5e6f7g8h9i0...",
  "key_prefix": "asn_live_k1a2",
  "permissions": ["read", "write", "activity:report"],
  "rate_limit_per_minute": 60,
  "created_at": "2026-03-18T12:00:00Z"
}

The key is hashed with a unique salt before storage. ASN never stores your raw key. If you lose it, revoke and create a new one.

Using a Key

Pass the key in the Authorization header with Bearer prefix:

curl https://asn.earth/api/v1/agents/ASN-2026-0384-7721-A \
  -H "Authorization: Bearer asn_live_k1a2b3c4d5e6f7g8h9i0..."

Permissions

API keys are scoped with granular permissions:

The default permission for new keys is read. Request only the permissions you need.

Revoking a Key

DELETE /api/v1/operators/me/api-keys/{key_id}

Revoked keys are kept in the database with a revoked_at timestamp for audit purposes. They cannot be reactivated. Create a new key instead.

Listing Keys

GET /api/v1/operators/me/api-keys

{
  "data": [
    {
      "id": "550e8400-...",
      "name": "Production Key",
      "key_prefix": "asn_live_k1a2",
      "permissions": ["read", "write", "activity:report"],
      "rate_limit_per_minute": 60,
      "status": "active",
      "last_used_at": "2026-03-18T14:30:00Z",
      "requests_count": 1247,
      "created_at": "2026-03-18T12:00:00Z"
    }
  ]
}

The list endpoint never returns the full key — only the prefix for identification.

Rate Limits

When rate limited, the API returns 429 Too Many Requests with a Retry-After header.

Public vs Authenticated Endpoints

Some endpoints are public and require no authentication:

Everything else requires either a session token or an API key.