Skip to main content

Agent Authentication Contract

This document defines the authentication contract for programmatic (agent/bot) access to ASG Agent Cloud.

Authentication Hierarchy

ASG Gateway supports two authentication methods, evaluated in order:
  1. SIWS Session Cookie (asg_session) — For console UI users
  2. Bearer Token API Key — For agents and programmatic access

API Key Format

Keys are 64-character random strings prefixed with environment indicator.

Security Model

Key Storage

  • Plain-text key: Shown ONCE at creation time — user must save it
  • Server stores: BCrypt hash only (cost=10)
  • No recovery: Lost keys cannot be retrieved; user must rotate

Scopes

Rate Limits

Limits are per-key, not per-wallet. 429 responses include Retry-After header.

Endpoints (Billing Plane)

Create Key

Response (201):

List Keys

Response:

Revoke Key

Rotate Key

Response: New key object (same as Create)

Validate Key (Internal)

Response:

Gateway Auth Middleware

The gateway validates keys via billing-plane /keys/validate with 5-minute caching.

Error Responses

Usage Example (Agent)