Authentication
The Nyne.ai Person and Company APIs authenticate with an API key and secret, sent as the X-API-Key and X-API-Secret headers. This is a key and secret pair, not a bearer token.
Below: where to get keys, how product access and optional IP-locking gate them, the auth error codes to branch on,
and how to rotate a key safely.
API key and secret
The Person and Company APIs (/person/* and /company/*) authenticate with a key and secret. The data API does not use bearer tokens. Send both values as the X-API-Key and X-API-Secret headers on every request:
curl -X POST https://api.nyne.ai/person/enrichment \ -H "X-API-Key: YOUR_API_KEY" \ -H "X-API-Secret: YOUR_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected]" }'
As a fallback, the same credentials also work as the api_key and api_secret request params (form fields or query string). Headers are
preferred - query strings can land in server logs and browser history:
curl "https://api.nyne.ai/person/enrichment?api_key=YOUR_API_KEY&api_secret=YOUR_API_SECRET&[email protected]"Always call from your backend
Get and manage keys
Create and manage keys on the API keys surface in your account. Click Create key to mint a key and secret pair. Keys are workspace-scoped: a key belongs to the workspace it was created in and inherits that workspace's subscription, credits, and rate limits. Switch workspaces and you get a different set of keys.
Programmatic management lives under the /v1/api-keys/* path family - list, create, and revoke keys from
code once you have an initial key.
Product access
A key is authorized per product. The three products are enrichment, search, and newsfeed, and each endpoint requires one of them. Authenticating
successfully does not by itself grant access to every endpoint.
Calling an endpoint your key is not entitled to returns 403 with subscription_required and a message like "Your subscription does not include access to the Search API." If your credentials are correct but one
endpoint keeps returning that code while others work, the key is missing that product - not misconfigured.
Right key, wrong product
subscription_required is an authorization result, not an authentication failure. The fix is to add
the product to your plan, not to rotate the key.IP-locking (optional)
A key can optionally be locked to an allow-list of IPs. Each entry can be an exact IP, a CIDR
range (v4 or v6), or an IPv4 wildcard like 203.0.113.*. Requests from any other address are rejected with 403 ip_not_allowed. The client IP is resolved in a Cloudflare-aware way,
so it reflects the true caller behind the proxy.
Locking is off until you add entries, and you enable and manage the allow-list from the same API keys surface. A key locked with an empty allow-list fails closed: it blocks every request. If you turn locking on, add at least one entry.
Auth error codes
Every reply uses the same envelope. When authentication or access fails, success is false and the detail moves under error. Branch on the stable error.code, not the human-readable message:
{
"success": false,
"error": {
"code": "invalid_credentials",
"message": "The API key or secret is invalid."
},
"timestamp": "2026-05-28T18:04:45"
}Each error.code maps to an HTTP status you can also switch on:
| error.code | HTTP | Meaning |
|---|---|---|
| missing_credentials | 401 | No key or secret was sent. |
| invalid_credentials | 401 | The key or secret is wrong or the key is disabled. |
| api_key_expired | 401 | The key is past its expiry date. |
| subscription_inactive | 403 | The subscription behind the key is not active. |
| subscription_required | 403 | The key or plan does not include this product. |
| ip_not_allowed | 403 | The request IP is not in the key's allow-list. |
| access_denied | 403 | The request does not belong to this key. |
| service_unavailable | 503 | Transient backend outage. Retry - do not rotate keys. |
Retry vs fix
503 service_unavailable is transient - back off and retry the same request; do not rotate keys.
A 401 means the credentials are wrong or expired, so fix or reissue them. A 403 means the credentials are valid but access is not granted - add the product, adjust the IP
allow-list, or check the subscription. Retrying a 401 or 403 unchanged will keep failing.Key hygiene and rotation
The secret is stored hashed and shown in full only once, at creation. Copy it immediately into your secret manager or environment - it cannot be retrieved again, only replaced. Treat the secret like a password: never commit it, log it, or embed it in client code.
To rotate a key with no downtime: create a new key, roll your traffic over to it, confirm the old key is idle, then delete the old key. If a secret is ever exposed, delete that key right away and issue a new one.
MCP authenticates differently
mcp__nyne__* tools, hosted at /mcp) authenticates over OAuth (well-known metadata plus JWKS), separate from this
data-API key and secret model. Do not reuse one for the other. See the MCP Quick Start for that flow.What's next
- Rate limits - per-key request ceilings and how to handle
429responses. - Credits - how usage is metered and when a request consumes a credit.
- Your first request - the submit-and-poll pattern every data endpoint shares.
- MCP Quick Start - wire Nyne.ai into Claude, ChatGPT, Cursor, and other AI clients over OAuth.