Authentication

API Authentication

Aegis uses a dual header authentication system to secure all API requests. Every authenticated endpoint requires both a Bearer token and the agent’s registered email address.

Keep your API token secure! Your token can perform any API action on behalf of your agent, including spending USDC. Never share it publicly or commit it to version control.

How Authentication Works

Unlike traditional API key systems, Aegis enforces zero-trust dual-header validation. Both headers must be present and must match the same agent record in the database:

Authorization: Your Bearer token issued during /v1/connect/complete
X-Aegis-Email: The email address associated with that token

This prevents cross-agent impersonation. Even if a token is intercepted, it cannot be used with a different email address.

Getting Your API Token

Aegis does not use a dashboard for token management. Tokens are issued programmatically through the Connect API:

Start onboarding

curl -X POST https://api.aegisintent.xyz/v1/connect/start \
  -H "Content-Type: application/json" \
  -d '{"email": "your-agent@example.com"}'

Complete with OTP

Check your email for a 6-character hex code, then submit it:

curl -X POST https://api.aegisintent.xyz/v1/connect/complete \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-agent@example.com",
    "challengeId": "YOUR_CHALLENGE_ID",
    "otp": "A8F93D"
  }'

Save the token

The response includes your token field. This is the only time you will see the plaintext token.

Token Format

Aegis API tokens follow a consistent prefix format:

Live Token: aegis_live_xxxxxxxxxxxxxxxx

Tokens are valid for 30 days from the date of issue. The tokenExpiresAt field in the connect response tells you the exact expiry timestamp.

Making Authenticated Requests

Include both headers on every request:

curl -X GET https://api.aegisintent.xyz/v1/actions/balance \
  -H "Authorization: Bearer aegis_live_wzm79d9Jzd7LMY4T2iOoW..." \
  -H "X-Aegis-Email: your-agent@example.com"

Request Headers

Every API request should include these headers:

Header	Value	Required
`Authorization`	`Bearer <your_token>`	Yes
`X-Aegis-Email`	`agent@example.com`	Yes
`Content-Type`	`application/json`	Yes (for POST requests)
`Idempotency-Key`	UUID v4	Required for financial actions
`X-Aegis-Nonce`	Integer	Required for financial actions

Idempotency

To prevent duplicate transactions, all financial action endpoints (/transfer, /pay, /bridge, /swap, /yield/deposit, /yield/withdraw, /wealth/limitOrder, /wealth/dca, /wealth/multiYield, /wealth/yield/synthra/withdraw) require an Idempotency-Key header. This must be a valid UUID v4. If you send the same request twice with the same idempotency key, Aegis will return the original response without executing the action again.

curl -X POST https://api.aegisintent.xyz/v1/actions/transfer \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Aegis-Email: your-agent@example.com" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Aegis-Nonce: 1" \
  -d '{
    "destination": "0x8E8F5064f20D235F899c7553F1BEE77A235F4828",
    "amount": "10.00"
  }'

Always use a fresh UUID for each new action. Reusing an idempotency key from a previous successful action will return the cached result, not execute a new one.

Nonce System

Aegis tracks an actionNonce for every agent. This counter increments on every successful financial action. You must pass the current nonce value in the X-Aegis-Nonce header for financial mutations. To check your agent’s current nonce:

curl -X GET https://api.aegisintent.xyz/v1/actions/nonce \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Aegis-Email: your-agent@example.com"

Response:

{
  "success": true,
  "nonce": 5
}

Error Handling

Authentication Errors

If authentication fails, you’ll receive an error response:

{
  "success": false,
  "error": "Unauthorized: Missing Bearer token",
  "code": "UNAUTHORIZED"
}

Authentication error codes:

Error Code	HTTP	Description
`UNAUTHORIZED`	401	Bearer token is missing, malformed, not found, or revoked
`TOKEN_EXPIRED`	401	Token has passed its 30-day expiry and was auto-revoked
`EMAIL_MISMATCH`	403	`X-Aegis-Email` header does not match the token’s agent
`MISSING_EMAIL_HEADER`	400	`X-Aegis-Email` header was not provided
`AGENT_SUSPENDED`	403	The agent account has been deactivated by an administrator
`TOKEN_IP_NOT_ALLOWED`	403	Request IP is not in the token’s allowed IP list

Token Revocation

To revoke all active tokens for an agent (e.g., in case of a token leak), call the revoke endpoint:

curl -X POST https://api.aegisintent.xyz/v1/connect/revoke \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Aegis-Email: your-agent@example.com"

Response:

{
  "success": true,
  "message": "All active tokens for this agent have been revoked."
}

After revocation, the agent must go through /v1/connect/start and /v1/connect/complete again to receive a new token.

Rate Limiting

Aegis enforces the following rate limits:

Scope	Limit
Connect API (`/v1/connect/*`)	10 requests per 10 minutes per IP
Actions API (`/v1/actions/*`)	120 requests per minute per agent
Marketplace API (`/v1/marketplace/*`)	90 requests per minute per agent
Policy API (`/v1/policy/*`)	60 requests per minute per agent

If you exceed the rate limit, you’ll receive a 429 Too Many Requests response.

Security Best Practices

Store Tokens Securely

Never hardcode tokens in your application source code
Use environment variables or a secrets manager
Rotate tokens by calling /v1/connect/revoke and Reonboarding

Use HTTPS Only

All API requests must use HTTPS, The API will reject plaintext HTTP connections

One Agent, One Token

For multi-agent architectures, provision separate agents (e.g., research-agent@company.com, trading-agent@company.com) rather than sharing a single token. This gives you independent audit trails and spending policies per agent.

Revoke on Compromise

If you suspect a token has been leaked, immediately call POST /v1/connect/revoke. This invalidates all active tokens for that agent instantly.

Authentication

API Authentication

How Authentication Works

Getting Your API Token

Token Format

Making Authenticated Requests

Request Headers

Idempotency

Nonce System

Error Handling

Authentication Errors

Token Revocation

Rate Limiting

Security Best Practices

Next Steps

Agent Connections

Quickstart

Documentation Index

​API Authentication

​How Authentication Works

​Getting Your API Token

​Token Format

​Making Authenticated Requests

​Request Headers

​Idempotency

​Nonce System

​Error Handling

​Authentication Errors

​Token Revocation

​Rate Limiting

​Security Best Practices

​Next Steps

Agent Connections

Quickstart

API Authentication

How Authentication Works

Getting Your API Token

Token Format

Making Authenticated Requests

Request Headers

Idempotency

Nonce System

Error Handling

Authentication Errors

Token Revocation

Rate Limiting

Security Best Practices

Next Steps