Authentication

AutopayOS supports multiple authentication methods depending on your use case. This guide covers API keys for server-side integration, JWTs for user sessions, and DIDs for agent identity.

API keys

API keys are the primary way to authenticate server-side requests. Keys are prefixed with ak_live_ for production or ak_test_ for sandbox.

Create an API key

Go to Dashboard → Settings → API Keys
Click Create API Key
Give your key a descriptive name
Copy the key immediately — it won't be shown again

Use your API key

Include your API key in the Authorization header:

Bash

curl https://api.autopayos.com/ap2/agents \
  -H "Authorization: Bearer ak_live_your_api_key"

Or in the SDK:

TypeScript

import { AutopayosClient } from '@autopayos/sdk';

const client = new AutopayosClient({
  baseUrl: 'https://api.autopayos.com',
  apiKey: process.env.AUTOPAYOS_API_KEY, // ak_live_...
});

</tab> <tab title="Python">

Python

from autopayos import AutopayosClient

client = AutopayosClient(
    base_url="https://api.autopayos.com",
    api_key=os.environ["AUTOPAYOS_API_KEY"]  # ak_live_...
)

</tab> </tabs>

API key security

Important: Keep your API keys secure. Never expose them in client-side code, public repositories, or logs.

Best practices:

Store keys in environment variables
Use different keys for production and testing
Rotate keys periodically
Revoke keys immediately if compromised

Key permissions

Permission	Description
`read`	Read agents, policies, evidence
`write`	Create intents, verify carts, execute payments
`admin`	Manage policies, revoke agents, configure webhooks

JWT authentication

For user-facing dashboards and web applications, AutopayOS uses Auth0 for JWT-based authentication.

OAuth flow

Diagram

┌──────────┐     ┌──────────┐     ┌──────────────┐
│  Client  │────▶│  Auth0   │────▶│  AutopayOS   │
│          │     │          │     │   Gateway    │
└──────────┘     └──────────┘     └──────────────┘
     │                │                   │
     │  1. Login      │                   │
     │───────────────▶│                   │
     │                │                   │
     │  2. JWT Token  │                   │
     │◀───────────────│                   │
     │                │                   │
     │  3. API Request with JWT           │
     │────────────────────────────────────▶
     │                │                   │
     │  4. Response                       │
     │◀────────────────────────────────────

Login endpoints

Endpoint	Description
`GET /ap2/auth/login`	Initiate OAuth login
`GET /ap2/auth/callback`	OAuth callback handler
`GET /ap2/auth/me`	Get current user info
`POST /ap2/auth/logout`	End session

Example: Get current user

Bash

curl https://api.autopayos.com/ap2/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response:

JSON

{
  "did": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSwuBV8xRoAnwWsdvktH",
  "email": "[email protected]",
  "role": "OWNER",
  "tenantId": "tenant_abc123"
}

Decentralized Identifiers (DIDs)

AutopayOS uses DIDs for cryptographic identity. Every agent and principal has a DID that identifies them across transactions.

DID format

AutopayOS supports did:key identifiers using Ed25519 keys:

Diagram

did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
       └─────────────────────────────────────────────────┘
                     Base58-encoded public key

Generate a DID

TypeScript

import { generateDid } from '@autopayos/crypto';

const { did, privateKey, publicKey } = await generateDid();

console.log(did);
// did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

</tab> <tab title="Python">

Python

from autopayos.crypto import generate_did

did, private_key, public_key = generate_did()

print(did)
# did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

</tab> </tabs>

DID roles

Role	Description	Example
Agent DID	Identifies an AI agent	Shopping assistant, booking agent
Principal DID	Identifies the human owner	The user who authorized the agent
Issuer DID	Identifies AutopayOS as VC issuer	System-level identity

Verifiable Credentials

DIDs are used to sign and verify Verifiable Credentials (VCs), which are the core data structures in AutopayOS.

VC structure

JSON

{
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  "type": ["VerifiableCredential", "IntentMandate"],
  "issuer": "did:key:z6Mk...",
  "credentialSubject": {
    "mandateId": "intent_abc123",
    "agentDid": "did:key:z6Mk...",
    "maxAmount": 100.00,
    "currency": "USD"
  },
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2025-12-17T10:00:00Z",
    "verificationMethod": "did:key:z6Mk...#key-1",
    "jws": "eyJhbGciOiJFZERTQSJ9..."
  }
}

Verify a VC

TypeScript

import { verifyVc } from '@autopayos/crypto';

const isValid = await verifyVc(intentVc);

if (!isValid) {
  throw new Error('Invalid credential signature');
}

Human Presence (WebAuthn)

For high-value transactions, AutopayOS can require Human Presence (HP) verification using WebAuthn/FIDO2.

When HP is required

HP is triggered based on policy rules:

Amount exceeds threshold (e.g., $500)
First transaction with a new merchant
Anomaly detected (unusual behavior)
Manual policy configuration

HP flow

Diagram

┌──────────┐     ┌──────────────┐     ┌──────────────┐
│  Agent   │────▶│  AutopayOS   │────▶│    User      │
│          │     │   Gateway    │     │  (Browser)   │
└──────────┘     └──────────────┘     └──────────────┘
     │                   │                    │
     │  1. Request       │                    │
     │──────────────────▶│                    │
     │                   │                    │
     │  2. HP Required   │                    │
     │◀──────────────────│                    │
     │                   │                    │
     │  3. Trigger WebAuthn                   │
     │───────────────────────────────────────▶│
     │                   │                    │
     │  4. HP Proof                           │
     │◀───────────────────────────────────────│
     │                   │                    │
     │  5. Submit with HP Proof               │
     │──────────────────▶│                    │

Register a WebAuthn credential

TypeScript

// Begin registration
const options = await fetch('/ap2/hp/webauthn/register/begin', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` },
  body: JSON.stringify({ agentDid: 'did:key:z6Mk...' }),
}).then(r => r.json());

// Create credential with browser API
const credential = await navigator.credentials.create({
  publicKey: options.publicKey,
});

// Complete registration
await fetch('/ap2/hp/webauthn/register/complete', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` },
  body: JSON.stringify({
    agentDid: 'did:key:z6Mk...',
    credential: credential,
  }),
});

See the Human Presence guide for complete implementation details.

Error codes

Code	Description
`401`	Missing or invalid authentication
`403`	Insufficient permissions
`INVALID_API_KEY`	API key is malformed or revoked
`TOKEN_EXPIRED`	JWT has expired
`DID_REVOKED`	Agent DID has been revoked

Authentication

API keys

Create an API key

Use your API key

API key security

Key permissions

JWT authentication

OAuth flow

Login endpoints

Example: Get current user

Decentralized Identifiers (DIDs)

DID format

Generate a DID

DID roles

Verifiable Credentials

VC structure

Verify a VC

Human Presence (WebAuthn)

When HP is required

HP flow

Register a WebAuthn credential

Error codes

Next steps