Authentication
Authenticate requests with bearer tokens, distinguish live from test keys, rotate secrets safely, and restrict access by IP.
Updated Sep 2026
Every request to the PARROTSIGHT API must carry an API key. Keys are scoped, revocable secrets issued from the Console, and they are the only credential the REST interface accepts — there is no long-lived username and password exchange for machine access.
Keys should be treated like any other production secret: never embed them in client-side code, never commit them to a repository, and prefer environment variables or a secret manager at runtime.
Bearer authentication
Pass the key in the Authorization header using the Bearer scheme. The header is required on every endpoint, including idempotent reads such as GET /v1/models.
curl https://api.parrotsight.com/v1/models \
-H "Authorization: Bearer $PS_API_KEY"Live and test keys
Keys are issued in two classes. Both carry the sk-ps- prefix so they are recognisable in logs and scanners, and both authenticate against the same base URL. The difference is what the request may touch behind the gateway.
| Property | Live key | Test key |
|---|---|---|
| Prefix | sk-ps-live-… | sk-ps-test-… |
| Billing | Counts against usage and invoices | Free, not metered |
| Model access | Stable and beta production models | Sandbox endpoints and deterministic fixtures |
| Rate limits | Full plan limits | Reserved test pool |
| Recommended for | Production workloads | CI, staging, and integration tests |
Key rotation best practices
Rotate keys on a schedule and whenever a key may have leaked. The Console supports overlapping validity windows so a rotation never interrupts traffic.
- Issue the replacement key first, then deploy it, then revoke the old key.
- Rotate quarterly as a baseline, and immediately on any suspected exposure.
- Issue one key per service or environment so damage can be revoked in isolation.
- Set an expiry on short-lived keys used by ephemeral workloads.
IP allowlist
Professional and Enterprise organisations may pin each key to a list of source IP ranges. Requests arriving from outside the allowlist are rejected with a 403 before reaching any model, which prevents a leaked key from being used from an untrusted network.
Configure the allowlist per key from the Console, or programmatically from the keys endpoint. Include your load balancers and egress proxies in CIDR form, and re-check the list whenever your network topology changes.
Was this helpful?
Your feedback shapes how we improve this documentation.