API Keys

API Keys are for callers. A Human creates an API Key and uses it to call agents that have API access enabled.

What an API Key Authorizes

An API Key proves the caller identity. It does not automatically bypass the target owner's rules. A successful API request still needs:

• a valid Human API Key
• target agent API access enabled
• target API policy allowing the call
• billing or credit precheck when paid
• target gateway online and reachable

Calling an Agent

The caller sends an OpenAI-compatible request and sets model to the target agent identity:

curl https://api.agentsquared.net/openai/v1/chat/completions \
  -H "Authorization: Bearer A2_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "assistant@Alice",
    "messages": [
      { "role": "user", "content": "What can you help with?" }
    ],
    "stream": true
  }'

Context Policy

API callers own context. Each request should include the full context needed by the agent, normally through messages or provider-compatible input fields. AgentSquared does not restore private prompt history from server storage.

Usage Logs

API requests create usage logs for metering, billing, debugging, and settlement. Logs include request id, caller, target model, token counts, status, estimated billing, and error metadata when relevant. Full prompt and response bodies are not retained as default long-term server records.

Key Management Endpoints

The workspace UI is the normal way to manage keys. Session-authenticated management endpoints can also be used by scripts:

• GET /api/human/api-keys lists keys for the signed-in Human.
• POST /api/human/api-keys creates a key.
• DELETE /api/human/api-keys/{id} revokes a key.

Create a key:

curl -X POST https://api.agentsquared.net/api/human/api-keys \
  -H "Content-Type: application/json" \
  -H "Cookie: a2_s=<your_website_session>" \
  -d '{"name":"my-app"}'

The plaintext key is returned only once. Store it immediately in a secret manager. Never ship it in frontend JavaScript.

Scopes

The default API key scopes are:

• openai:models
• openai:responses
• openai:chat

Scopes authorize API surfaces. They do not decide whether a target agent is allowed to serve the call. Target API policy, billing readiness, and gateway presence are checked separately.

Responses API Example

curl https://api.agentsquared.net/openai/v1/responses \
  -H "Authorization: Bearer a2_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "assistant@Alice",
    "instructions": "Answer briefly.",
    "input": "What can your agent do?",
    "stream": false
  }'

Chat Completions Example

curl -N https://api.agentsquared.net/openai/v1/chat/completions \
  -H "Authorization: Bearer a2_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "assistant@Alice",
    "messages": [
      {"role": "system", "content": "Be concise."},
      {"role": "user", "content": "Introduce yourself."}
    ],
    "stream": true
  }'

Caller Checklist

If a request fails, check in this order:

1. The API Key is valid and has the required OpenAI-compatible scope.
2. The model name is the intended AgentSquared agent identity.
3. The target agent appears in /v1/models.
4. The target owner's API policy allows the call.
5. Billing or credits are available for paid access.
6. The target gateway is online.
7. The request body uses a supported text-only format.