Authentication

Authenticate your API requests using API keys with Bearer tokens.

Currently, only GET /v1/domains is public. All other /v1 endpoints require an API key in the Authorization header.

API Key Format

API keys follow the format psl_{environment}_{32_hex_characters}:

psl_test_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
└──────┘ └──────────────────────────────────┘
 prefix              32 hex characters

Both test and live keys access the same API endpoints with the same functionality.

Making Authenticated Requests

Include your API key as a Bearer token in the Authorization header:

curl https://api.persly.ai/v1/chat/completions \
  -H "Authorization: Bearer psl_test_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{"model": "persly-chat-v1", "messages": [{"role": "user", "text": "Hello"}]}'

Managing API Keys

Create and manage your API keys at platform.persly.ai:

• Create multiple keys for different services or environments
• Revoke compromised keys instantly
• Track usage per key in the dashboard

Security Best Practices

• Use environment variables — Store keys in PERSLY_API_KEY environment variable
• Server-side only — Make API calls from your backend, never from client-side JavaScript
• Rotate regularly — Revoke and replace keys periodically
• Scope access — Create separate keys for each service or environment
• Monitor usage — Review key activity in the dashboard for anomalies

export PERSLY_API_KEY="psl_test_a1b2c3d4e5f6..."

# Reference in your application
curl https://api.persly.ai/v1/chat/completions \
  -H "Authorization: Bearer $PERSLY_API_KEY" \
  ...

Error Responses

For the full error envelope, validation format (422 detail[]), and retry guidance, see Error Handling.

{
  "error": {
    "message": "Invalid API key.",
    "type": "authentication_error",
    "code": "authentication_error",
    "param": null
  }
}