AIM REST API reference

Complete API documentation for Agent Identity Management with interactive examples

Base URL

https://aim.example.com/api/v1

Authentication

Bearer Token / API Key

Response format

application/json

Authentication methods

JWT bearer token (web UI and user access)

Used for web interface and user-authenticated requests. Obtained via login endpoint.

curl -H "Authorization: Bearer {access_token}" https://aim.example.com/api/v1/agents

API key (SDK and programmatic access)

Used for SDK and automated agent operations. SHA-256 hashed with rate limiting.

curl -H "X-API-Key: {api_key}" https://aim.example.com/api/v1/sdk-api/agents/my-agent

Agent signature (MCP attestation and SDK routes)

Used by an agent to sign its own requests with the Ed25519 private key it registered. The signed message is the HTTP method, the request path with its query string, the Unix timestamp and the request body (left out when empty), joined by newlines. The timestamp must be within 30 seconds of the server clock, and X-Public-Key must match the agent's registered key. Send no Authorization header on a signed request.

curl -H "X-Agent-ID: {agent_id}" \
  -H "X-Timestamp: {unix_timestamp}" \
  -H "X-Public-Key: {ed25519_public_key_base64}" \
  -H "X-Signature: {ed25519_signature_base64}" \
  https://aim.example.com/api/v1/mcp-servers/{mcp_server_id}/attestations

SDK download and zero-config setup

AIM provides pre-configured SDKs with embedded credentials, so no API keys or configuration are needed.

Download SDK endpoint

curl -X GET https://aim.example.com/api/v1/sdk/download \
  -H "Authorization: Bearer {access_token}" \
  -o aim-sdk.zip

Using the SDK (one line)

# Extract and use - no pip install needed!
from aim_sdk import secure

# Your agent is now secure with zero configuration
agent = secure("my-agent")

Rate limiting

All API endpoints implement rate limiting for security and performance:

Authenticated requests: 1000 requests per minute
Public endpoints: 100 requests per minute
SDK API (with API key): 5000 requests per minute
Auth endpoints: 10 requests per minute (prevent brute force)

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Error responses

All errors follow a consistent format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "email",
      "reason": "Invalid email format"
    }
  },
  "request_id": "req_123abc",
  "timestamp": "2024-01-01T12:00:00Z"
}

Common error codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Rate Limited

500 Server Error