Skip to main content

​
Authentication

Amrood uses API keys for authentication. There are two modes:

​
Platform Authentication

Used by developers making server-to-server calls. Grants access to all agents under the platform. 
x-platform-id: plt_abc123
x-platform-secret: sk_live_xxxxx
Platform keys can:
  • Create and manage owners
  • Create and manage agents
  • Access any agent’s wallet and transactions
  • Update spend policies

​
Agent Authentication

Used by AI agents making their own calls. Scoped to a single agent’s wallet. 
x-agent-key: agk_live_xxxxx
Agent keys can:
  • Check their own balance
  • Fund their wallet
  • Make payments
  • View their transaction history
Agent keys cannot:
  • Access other agents’ data
  • Create owners or agents
  • Override spend policies

​
Owner Session Authentication

Used by account holders to manage their agents, approve transactions, and configure policies. Authenticate via OTP: 
# Send OTP
POST /v1/auth/send-otp
{ "phone": "9876543210" }

# Verify OTP
POST /v1/auth/verify-otp
{ "phone": "9876543210", "code": "123456" }
Session cookie (amrood_session) is set automatically. Owner session can:
  • View and manage their agents
  • Approve or reject pending transactions
  • Configure organization budgets
  • Manage agent certificates

​
Admin Authentication

OTP-only access for platform administrators. See Admin Dashboard for details.

​
Security

  • All API keys are hashed with bcrypt before storage — raw keys are never persisted
  • Keys are returned exactly once at creation time
  • Rate limiting: 100 req/min per agent, 1000 req/min per platform, 30 req/min unauthenticated
  • All transactions require an idempotency_key to prevent duplicate processing
  • Agent key rotation available via POST /v1/agents/{agent_id}/rotate-keys
  • Platform-signed network proofs via GET /v1/agents/me/proof (Ed25519, 1-hour TTL)

​
Error Responses

Invalid or missing credentials return: 
{
  "error": {
    "code": "authentication_error",
    "message": "Invalid or missing API key"
  }
}