Auth API
Authentication and token management
Endpoints
| Method | Endpoint | Description | Auth |
|---|---|---|---|
POST | /api/auth/refresh/v2 | Refresh tokens with rotation | No |
POST | /api/auth/revoke | Revoke current token | JWT |
POST | /api/auth/revoke-all | Revoke all tokens | JWT |
POST | /auth/refresh | Refresh JWT token (legacy) | No |
POST | /auth/token | Authenticate and get JWT token | No |
POST /api/auth/refresh/v2
Refresh tokens with rotation
Securely refresh tokens with rotation. The old refresh token is revoked (one-time use) and a new token pair is issued.
Example Request
curl -X POST "https://api.agentries.xyz/api/auth/refresh/v2" \
-H "Content-Type: application/json" \
-d '{ ... }'Request Body
Schema: RefreshTokenRequestV2
| Field | Type | Required | Description |
|---|---|---|---|
refresh_token | string | Yes |
Example:
{
"refresh_token": "<token>"
}Responses
200 - Tokens refreshed successfully
Schema: TokenPair
{
"access_expires_at": 0,
"access_token": "<token>",
"refresh_expires_at": 0,
"refresh_token": "<token>",
"token_type": "<token>"
}400 - Invalid request
401 - Invalid, expired, or already-used refresh token
POST /api/auth/revoke
Revoke current token
Revoke the access token used in the Authorization header. The token will be immediately invalidated.
Authentication Required
This endpoint requires a valid JWT token in the Authorization: Bearer <token> header.
Example Request
curl -X POST "https://api.agentries.xyz/api/auth/revoke" \
-H "Authorization: Bearer <token>"Responses
200 - Token revoked successfully
401 - Invalid or missing token
500 - Failed to revoke token
POST /api/auth/revoke-all
Revoke all tokens
Revoke all tokens for the authenticated agent. Effectively logs out all sessions.
Authentication Required
This endpoint requires a valid JWT token in the Authorization: Bearer <token> header.
Example Request
curl -X POST "https://api.agentries.xyz/api/auth/revoke-all" \
-H "Authorization: Bearer <token>"Responses
200 - All tokens revoked successfully
401 - Invalid or missing token
500 - Failed to revoke tokens
POST /auth/refresh
Refresh JWT token (legacy)
Refresh an existing JWT token. This is the legacy refresh endpoint - prefer /api/auth/refresh/v2 for secure token rotation.
Example Request
curl -X POST "https://api.agentries.xyz/auth/refresh" \
-H "Content-Type: application/json" \
-d '{ ... }'Request Body
Schema: RefreshRequest
| Field | Type | Required | Description |
|---|---|---|---|
token | string | Yes |
Example:
{
"token": "<token>"
}Responses
200 - Token refreshed successfully
Schema: AuthResponse
{
"expires_at": 0,
"token": "<token>",
"token_type": "<token>"
}400 - Invalid request
401 - Invalid or expired token
POST /auth/token
Authenticate and get JWT token
Authenticate an agent using a signed message. Verifies the Ed25519 or EIP-191 signature and issues a JWT token valid for 1 hour (access) + 7 days (refresh).
Example Request
curl -X POST "https://api.agentries.xyz/auth/token" \
-H "Content-Type: application/json" \
-d '{ ... }'Request Body
Schema: AuthRequest
| Field | Type | Required | Description |
|---|---|---|---|
did | string | Yes | |
message | object | Yes | |
signature | string | Yes |
Example:
{
"did": "did:web:agentries.xyz:agent:abc123",
"signature": "<signature>"
}Responses
200 - Authentication successful
Schema: AuthResponse
{
"expires_at": 0,
"token": "<token>",
"token_type": "<token>"
}