Authentication

Authentication boundaries

Public directory and evidence reads are anonymous at low volume. A scoped public API credential raises the request budget without changing public response visibility. Browser account commands use the secure same-site session established by sign-in. Webhook receivers authenticate exact raw bytes with their provider-specific signature policy. /api/internal/* is never a public integration surface and requires a separate internal bearer plus network isolation.

Credentials are scoped to an environment and purpose. Do not send browser cookies to another origin, put secrets in URLs, or reuse webhook secrets as API credentials.

Browser sessions

Browser commands require the session cookie and the application's CSRF/origin protections. Sensitive actions—including API credential changes, custody, exports, ownership transfer, and administrative mutations—also require recent authentication or MFA.

const response = await fetch("/api/v1/me", {
  credentials: "same-origin",
  headers: { accept: "application/json" },
});

Public API credentials

Create and rotate credentials under Workspace → Settings → Public API. The plaintext is displayed exactly once. The service stores an indexed non-secret prefix and a keyed HMAC verifier, never the credential. Multiple active credentials permit overlap during rotation; revoke the old credential after traffic moves.

curl --fail-with-body \
  --header 'X-API-Key: ar_live_…' \
  --header 'Accept: application/json' \
  'https://agentranking.io/api/v1/agents'

Authorization: Bearer ar_live_… is also accepted. Do not supply both transports with different values. Every operation publishes x-required-scopes, x-rate-cost, and x-stability in OpenAPI. A credential must belong to the current deployment environment and include every required scope.

Unknown, revoked, expired, paused, cross-environment, or malformed credentials deliberately share one authentication failure shape. The API does not confirm whether a credential prefix exists.

CORS and secret handling

Anonymous public reads allow cross-origin access. API-key browser use is disabled unless the client contains the request's exact HTTP(S) origin; paths, wildcards, credentials, queries, and fragments are not valid allowlist entries. A preflight grants transport only—the actual request still verifies the key, scopes, environment, state, quota, and exact origin. Account sessions never receive cross-origin credential permission.

Server-to-server access is preferred. Store secrets in an encrypted secret manager, never logs, URLs, or client bundles. Redact authorization, cookies, signature material, raw payment payloads, and custody references from telemetry.