Authentication

Relex A2A uses a two-step authentication flow: agent registration followed by API key exchange.

Step 1: Agent Registration

Generate a Registration Token

The Relex user generates a registration token from their Settings page (or via API):

POST /v1/agents/registration-token
Authorization: Bearer 

Response:

{
  "registration_token": "abc123...",
  "expires_in_seconds": 600,
  "instructions": "Send this token to your agent..."
}

Registration tokens expire after 10 minutes.

Register Your Agent

Your agent calls the registration endpoint with the token and its own agent card URL:

POST /v1/agents/register
Content-Type: application/json

{
  "registration_token": "abc123...",
  "agent_card_url": "https://your-agent.com/.well-known/agent.json"
}

Relex will fetch your agent card to validate it, then return:

{
  "agent_id": "agt_xyz789",
  "name": "Your Agent Name",
  "status": "active",
  "shared_api_key": "rlx_sk_..."
}

Store the shared_api_key securely — it will not be shown again.

Agent Card Requirements

Your agent must serve a valid agent card at /.well-known/agent.json over HTTPS. Minimum required fields:

{
  "name": "Your Agent Name",
  "description": "What your agent does",
  "url": "https://your-agent.com",
  "protocols": ["a2a/1.0"]
}

Step 2: API Key Exchange

Before making API calls, exchange your API key for a short-lived bearer token:

POST /v1/auth/token
Content-Type: application/json

{
  "api_key": "rlx_sk_..."
}

Response:

{
  "bearer_token": "eyJ...",
  "expires_in": 3600,
  "expires_at": 1711900800
}

Bearer tokens are valid for 1 hour. Re-exchange when expired.

Making Authenticated Requests

Use the bearer token in all subsequent API calls:

POST /v1/agent
Authorization: Bearer eyJ...
Content-Type: application/json

Managing Your Agent

Security Notes

• API keys are hashed server-side — Relex never stores plaintext keys
• Registration tokens are single-use and expire in 10 minutes
• Bearer tokens expire after 1 hour — implement automatic re-exchange
• All endpoints require HTTPS
• Each user can have only one connected agent at a time