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
Authorization: Bearer asc_sk_...

​
API Key Format

PrefixEnvironmentExample
asc_sk_live_Productionasc_sk_live_abc123...
asc_sk_test_Staging/Devasc_sk_test_xyz789...
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

ScopeDescription
readQuery balance, history, usage stats (default)
fundInitiate deposits, manage billing (requires opt-in)

​
Rate Limits

TierRPM LimitDefault
Free60✓
Plus300
Pro1000
Limits are per-key, not per-wallet. 429 responses include Retry-After header.

​
Endpoints (Billing Plane)

​
Create Key

POST /keys
Content-Type: application/json
Cookie: asg_session=...

{
  "name": "My Agent Bot",
  "scopes": ["read"],
  "rate_limit_rpm": 60
}
Response (201): 
{
  "key_id": "key_abc123",
  "api_key": "asc_sk_live_...",  // ⚠️ SHOW ONCE
  "name": "My Agent Bot",
  "scopes": ["read"],
  "rate_limit_rpm": 60,
  "created_at": "2026-02-03T12:00:00Z"
}

​
List Keys

GET /keys
Cookie: asg_session=...
Response: 
{
  "keys": [
    {
      "key_id": "key_abc123",
      "name": "My Agent Bot",
      "prefix": "asc_sk_live_abc...",  // First 16 chars only
      "scopes": ["read"],
      "rate_limit_rpm": 60,
      "last_used_at": "2026-02-03T11:30:00Z",
      "created_at": "2026-02-03T10:00:00Z"
    }
  ]
}

​
Revoke Key

DELETE /keys/:key_id
Cookie: asg_session=...

​
Rotate Key

POST /keys/:key_id/rotate
Cookie: asg_session=...
Response: New key object (same as Create)

​
Validate Key (Internal)

POST /keys/validate
Content-Type: application/json

{ "api_key": "asc_sk_live_..." }
Response: 
{
  "valid": true,
  "key_id": "key_abc123",
  "owner_wallet": "ABC...xyz",
  "scopes": ["read"],
  "rate_limit_rpm": 60
}

​
Gateway Auth Middleware

The gateway validates keys via billing-plane /keys/validate with 5-minute caching. 
// Request gets decorated with:
interface AuthenticatedRequest extends Request {
  apiKeyId?: string;       // e.g., "key_abc123"
  ownerWallet?: string;    // Wallet that created the key
  scopes?: string[];       // ["read"] or ["read", "fund"]
  rateLimitRpm?: number;   // Per-key rate limit
}

​
Error Responses

StatusCodeDescription
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENMissing required scope
429RATE_LIMITEDRate limit exceeded

​
Usage Example (Agent)

const response = await fetch('https://agent.asgcompute.com/v1/account/balance', {
  headers: {
    'Authorization': 'Bearer asc_sk_live_your_key_here',
    'Content-Type': 'application/json'
  }
});

if (response.status === 401) {
  // Re-authenticate or refresh key
}

const balance = await response.json();