API Authentication

Authenticate with the Proxies.ai control plane API.

The Proxies.ai API base URL is https://proxies.ai/api. All endpoints require authentication except the health endpoint.

Authentication Methods

The API accepts three authentication methods:

Bearer API Key

Pass a cifp_-prefixed API key in the Authorization header:

bash

curl https://proxies.ai/api/proxies \
  -H "Authorization: Bearer cifp_your_api_key_here"

API keys are created in the dashboard or via POST /api/keys. They can be scoped to specific operations and revoked independently.

Bearer OAuth Access Token (CLI)

The Proxies.ai CLI authenticates via Logto's OAuth 2.0 device flow (RFC 8628). The resulting JWT is verified against Logto's JWKS endpoint. The token'saud must include the Proxies.ai API resource indicator, and scopes are extracted from the scope claim.

bash

# The CLI handles this automatically after 'cifp login'
curl https://proxies.ai/api/proxies \
  -H "Authorization: Bearer eyJhbGciOi..."

Browser Session

Dashboard users are automatically authenticated via Logto session cookies when making API calls from the browser. No additional configuration needed.

Error Responses

Status	Meaning
400 Bad Request	Invalid request body. Check the details field for schema errors.
401 Unauthorized	No credential, invalid key, or revoked key.
403 Forbidden	Authenticated but insufficient scope or not a paid user.
404 Not Found	Resource doesn't exist or belongs to a different tenant.
409 Conflict	Duplicate resource (e.g. secret name already exists).
429 Too Many Requests	Rate limit exceeded. Retry after the Retry-After header.
500 Internal Server Error	Unexpected server error.

Rate Limits

All API endpoints are rate-limited per IP. Limits are applied using a sliding window. When exceeded, the API returns 429 with a Retry-After header indicating when the window resets.

Pagination

List endpoints return up to their stated maximum per request. Use thelimit query parameter to control the page size. Cursor-based pagination may be added in a future release.

Base URL

bash

https://proxies.ai/api