API Keys and Connected Apps
Create, narrow, roll and revoke API keys, manage connected AI apps, and call the API from your own software.
Give your own software, or an AI assistant you use, limited access to your websites, and end that access whenever you choose. API keys and connected AI apps are managed together in Dashboard → Account → API keys and AI apps. This page explains both, and the API tile in Dashboard → Integrations that shows how many keys reach a website. The two other ways AI reaches NovixAgent AI are described in AI Agents on Your Site and Your AI Assistant.
Keys and connected apps at a glance
Only the keys and connections you create here get in.
| API key | Connected AI app | |
|---|---|---|
| What it is | A secret that your own software sends with each request | The connection of an AI assistant you allowed on a consent page |
| Belongs to | The account, so it keeps working when the person who created it leaves or hands the account over | You as a person |
| Created by | Create key, by the account owner | The app, once you allow it |
| Reaches | The websites you picked, or the account's websites including ones added later | The websites you chose on the consent page |
| Ends | On its expiry date, or when you revoke it | On the end date the consent page showed, or when you revoke it |
The API tile
The API tile in Dashboard → Integrations is for your developer or agency. It shows how many API keys reach the website and links to Manage keys in Account; keys are created and ended in your account, not on the tile. The tile shows a lock when the website's plan does not include the API. If it says new keys are not available right now, the feature has not been opened for your account yet. Existing keys can still be narrowed or revoked.
Create a key
- Open Dashboard → Account → API keys and AI apps and press Create key.
- Give the key a Name that tells you where it is used, such as the software it belongs to.
- Choose the Sites it can reach: your sites including ones you add later, or only the sites you pick.
- Tick What it can do. Pick only what the software needs.
- Choose Expires after. A key has an expiry date.
- Optionally list Allowed addresses: one address or range per line. Leave it empty if the key should work from wherever your software runs.
- Confirm with your password and, if you use two-factor authentication, a current code, then press Create key.
The full key is shown once, under Copy your new key now. Store it in your software's secret settings straight away; if you lose it, create a new one. We keep only a fingerprint of it. Each key starts with nva_, so a secret scanner can recognise it.
If your account has no password
An account created through Google starts without a password of its own, and creating or rolling a key, or changing the addresses it allows, is confirmed with one. The dialog then shows Set a password first: choose Set a password by email, set one from the link we send, and return. See also Your password.
What a key can do
A key carries only the permissions you tick, and it does not do more than you can do yourself in the dashboard.
| Permission | What it allows |
|---|---|
| Sites | See which sites you have and their basic details |
| Leads (read) | Read the leads your assistant captured |
| Leads (export) | Export your leads in bulk |
| Conversations (read) | Read chat conversations and their transcripts |
| Analytics (read) | Read your site analytics |
| Chat | Ask your assistant questions as a visitor would. Each question uses one of your plan's messages |
| Knowledge base (read) | Read your knowledge base entries |
| Knowledge base (write) | Add and change knowledge base entries |
| Widget settings (write) | Change how your chat widget looks and behaves |
| Webhooks (manage) | Send a test delivery to a webhook, list failed deliveries, and retry or abandon one. Webhooks themselves are added and changed in the dashboard |
| Live chat (read) | Read live chat conversations your team handles |
A few settings stay with the dashboard even for a key with the widget permission: a key does not change a transcript policy or an address, and the API refuses it with a typed code.
Sites, expiry and addresses
- Sites. A key reaches the websites of the account it belongs to, not someone else's. A website whose plan does not include the API refuses the key, even though the key stays listed.
- Expiry. Choose how long the key lives from the options in the dialog. We email the account owner shortly before a key expires, so you can roll it in time.
- Allowed addresses. With a list, the key works only from those addresses and ranges, IPv4 or IPv6. A request from another address is refused as if the key were not valid.
Roll, narrow and revoke
- Roll replaces a key with a new one of the same access. Put the new key into your software; the old one stops at once, or keeps working for a day or a week, as you choose. Rolling a key is how you replace a secret that may have leaked, or renew one before it expires.
- Narrow makes a key reach less: fewer sites, or a changed list of allowed addresses. A key can only lose access this way; to give software more, create a new key. Changing the address list asks for your password.
- Usage shows what the key did over a recent period, per website and kind of operation. These are counts only.
- Revoke ends one key or app at once. Software that uses a revoked key is refused from its next request. A second button on the card ends your keys and connected AI apps together. It asks you to confirm and is not undone.
Keys belong to the account
An API key belongs to the account it was created in, and the person who created it is recorded as its issuer. Software that runs on a key keeps working when someone leaves the team or when ownership of the account is handed over; the key then acts as the new owner. The new owner receives an email with the list of keys to review. The list changes no key, so a handover does not interrupt your integrations, and the new owner can revoke a key they do not recognise.
If a security event ends a person's access, for example a suspension, the keys that person created are revoked with it. A key created by another member of the account is not affected.
Connected AI apps work differently: they belong to the person who connected them. See Your AI Assistant.
Emails about your keys
We email the account owner when a key is created or rolled, so a key made without your knowledge shows up; shortly before keys expire; when a security event makes it worth reviewing the keys and apps that are live; and when an app is connected. A review email lists the live keys and apps and links to the ones to look at, which show a From your email badge in the list. A key or connection that has already ended is no longer listed.
Connected AI apps
Connected AI apps are the connections of the AI assistants you allowed. Each row shows the app, the sites it reaches, what it may do, when it was last used and whether it is Connected. A row marked Disconnected no longer holds a live connection: connect the app again from its own settings, or revoke the row. How to connect an assistant is in Your AI Assistant.
Calling the API
Your software sends the key in the Authorization header as Bearer <key>, to the endpoints under /v1/public-api. The API speaks JSON, lists are paged with a cursor, and each endpoint needs one of the permissions above. A key is accepted on API endpoints only; it does not work on the dashboard's own routes, and a request that carries both a cookie and a key is refused.
Each response to a key carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, so your software can see its own rate. When a limit is reached the answer is a refusal with a Retry-After header. Errors are RFC 9457 problem documents, sent as application/problem+json. Each carries type (about:blank), title (the HTTP status phrase), status and detail, a sentence for a person that may be reworded, so branch on code. Where they apply it also carries code, a typed refusal code, request_id to quote to support, and retry_after_seconds, the same wait as the Retry-After header:
| Status | code |
Meaning |
|---|---|---|
| 401 | CREDENTIAL_REQUIRED |
The endpoint takes a key and the request carried no key. |
| 401 | CREDENTIAL_INVALID |
The key is malformed, unknown, revoked or expired, sent from an address not on its list, or its owner is suspended. One code is used for these reasons so that guessing keys reveals no state. |
| 403 | SCOPE_MISSING |
The key does not carry the permission the endpoint needs. |
| 403 | SITE_NOT_IN_SCOPE |
The website is yours but outside the sites this key reaches. |
| 403 | PLAN_TIER_TOO_LOW |
The website's plan does not include the API. |
| 400 | FIELD_NOT_WRITABLE_BY_KEY |
A widget-settings write names a field only the dashboard may set. |
| 400 | CREDENTIALS_AMBIGUOUS |
A cookie and a key were sent together. |
| 429 | RATE_LIMITED |
A limit was reached, and the call did not run. Retry after the time given. |
| 429 | CONCURRENCY_LIMIT |
The service is busy with other calls, and the call did not run. Retry after the time given. |
| 404 | DOOR_CLOSED |
The API has not been opened for the account. |
| 400 | CURSOR_NOT_ISSUED |
The cursor is not one this list issued. Start the list again without a cursor. |
| 400 | INSTANT_INVALID |
A time bound is not a valid UTC instant such as 2026-10-21T10:00:00Z. |
| 404 | RESOURCE_NOT_FOUND |
The item is not on that website, whether it does not exist or belongs to another one. |
| 429 | RESOURCE_BUSY |
Another change to the same item is running, and the call did not run. Retry after the time given. |
A piece of a knowledge base document, called a chunk, is named by an opaque id rather than a sequence number. Take the id from the list of a document's chunks and send it back to rewrite that chunk; an id that no longer matches a piece is refused with a typed code.
The live chat list takes status as open, closed or all; without it, the list holds the open conversations.
The endpoints and their fields are described in an OpenAPI document. Your developer can ask support@novixagent.ai for the current copy.
If it isn't working
| What the screen says | What to do |
|---|---|
| The dialog says you have reached the most API keys an account may hold | Revoke a key you no longer use, then create the new one. |
| The dialog says a key can only lose access | Narrowing does not widen a key. To give software more, create a new key with the access you want. |
| The dialog says the account is not one that holds API keys | Staff accounts do not hold keys. Use a customer account for integrations. |
| API access is not available for your account right now | The feature has not been opened for your account yet. |
| Enter your account password to continue / Enter a current code from your authenticator to continue | These acts are confirmed. Enter what is asked. A code that was already used is refused; wait for the next one. |
| Too many attempts | Wait a while before you try again. |
| Another change to your keys is still running | Try again in a moment. |
The software gets CREDENTIAL_INVALID |
The key may have expired, been revoked, or be used from an address not on its list. Create or roll a key. |
Plan and limits
Which plans include the API: What each integration allows, by plan. Rates, and how the monthly messages are shared with the chat, are in AI Agent Access: Limits and Plans. Live keys per account are limited; the dialog tells you when you have reached the limit.