Authentication
Authenticate every request with an API key in the x-api-key header, and check that your key works.
The Knock API authenticates requests with an API key sent in the x-api-key header. Each key belongs to one Knock account, and everything you create with it (enrichment requests, contacts, credit usage) is scoped to that account.
curl https://app.knock-ai.com/resources/whoami/v1 \
-H "x-api-key: $KNOCK_API_KEY"Get an API key
API keys are issued by Knock. Ask your Knock account team, or your shared Slack channel with Knock, for a key with the role your integration needs:
| API | Role |
|---|---|
| Enrichment API | Enrichment API |
| Chats and meetings | Viewer (Editor, CRM Admin and AI Manager also work) |
- Use the narrowest role. An Enrichment API key can't read chats or meetings, and a Viewer key can't use the Enrichment API: if you need both, use two keys. Admin keys work everywhere but carry full admin access.
- A key is shown once, when it's issued. Knock can't show it to you again; if you lose it, ask for a new one.
- Keys start with
KNK-. That prefix makes them easy to spot in secret scanners and logs. - A key can be issued with an expiry date. After it expires, every request with it gets
401.
Keep your key secret
- Call the API only from your backend. Never put a key in browser JavaScript, a mobile app or a public repository.
- Load the key from an environment variable or a secrets manager, not from source code.
- Use a separate key per integration or environment, so you can revoke one without breaking the others.
- If a key leaks, ask your Knock account team to revoke it right away and issue a replacement. A revoked key gets
401on every request.
Verify your API key
GET /resources/whoami/v1 returns the ID of the Knock account a key belongs to. It's free and has no side effects, so it's the right first call for a new integration and a good health check.
Verify your API key
Sends GET /resources/whoami/v1 from your browser directly to app.knock-ai.com. Free and read-only. The key is not stored and never reaches this site's servers.
If your account restricts API access to specific IP addresses, the browser check fails with ip-restriction.denied. Run the same request from an allowed server instead:
curl -i https://app.knock-ai.com/resources/whoami/v1 \
-H "x-api-key: $KNOCK_API_KEY"{
"vendorId": "3f6a2b1c-8d4e-4f5a-9b6c-7d8e9f0a1b2c"
}A valid key isn't always an authorized key
The verify endpoint accepts any key issued for API access, whichever endpoints it can use. To confirm the key can use the Enrichment API without spending credits, read an enrichment request that doesn't exist, for example GET /v1/enrichment-requests/00000000-0000-4000-8000-000000000000. A 404 with code external-api.enrichment-request.not-found means the key has access; a 403 with code permissions.denied means it doesn't. For chats and meetings, a 200 from GET /v1/meetings?limit=1 means the key has access.
Verify calls count toward your rate limit like any other request. Full schema: Verify API key.
Authentication errors
Every error has the same JSON body. The code field tells you exactly what went wrong:
{
"errors": ["Invalid authentication token"],
"code": "authentication.invalid",
"metadata": {}
}| Status | code | What it means | What to do |
|---|---|---|---|
401 | authentication.invalid | The x-api-key header is missing, or the key is unknown, revoked or expired. Knock also returns this when it can't verify a key for a moment. | Check the header name and the key. If a key that worked a moment ago starts failing, retry a few times with backoff before treating it as revoked. |
401 | authentication.forbidden | The request comes from a country Knock doesn't serve. | Send requests from servers in a supported location. |
403 | permissions.denied | The key is valid but its role can't use this endpoint. | Use a key with the right role. |
403 | ip-restriction.denied | Your account only allows API access from specific IP addresses, and this request came from another one. | Send requests from an allowed IP, or ask your Knock admin to add your server's outbound IP. |
Knock fails closed
If Knock can't confirm that a key is valid, for example during a brief internal disruption, it rejects the request with 401 authentication.invalid rather than letting it through. A short burst of 401s from a key that worked a moment ago doesn't mean the key was revoked: retry with exponential backoff, and only alert after several consecutive failures.
See Errors for every other error code.