Integrate with an AI agent
Many Noxtica integrations are written with an AI coding agent or an AI assistant. This page shows how to give such an agent the documentation in a form it can read, the order of steps it follows, the rules it must keep, and prompts to start from. Everything the agent needs is published on these pages; it needs no private repository and no credential to read them.
Availability is account-specific, as everywhere in the documentation: the modules enabled for your organisation decide which steps apply to you.
Give the agent the documentation
Every documentation page is published as clean Markdown, without navigation, search box, table of contents or footer text. Choose the surface that fits the agent’s context window.
| Surface | URL | Use it when |
|---|---|---|
| Index | llms.txt | The agent should find the right page itself. Pages are grouped by task, in integration order, one line each. |
| Full text | llms-full.txt | The agent can read the whole documentation in one go. The file is large: llms.txt states its size. It leaves out the generated API reference pages, which the OpenAPI files cover. |
| One page | https://noxtica.com/docs/<path>/index.md, for example Getting Started | The task names a page. The body is the page text, with frontmatter (title, description, canonical_url, last_updated, section) and absolute links. |
| Content negotiation | The page URL with the request header Accept: text/markdown | The agent already has the page URL. The response is the same document as the index.md URL. |
| OpenAPI | openapi.json or openapi.yaml | The agent generates or checks client code. One document with every public operation, parameter and webhook of the published release. |
| One API | https://noxtica.com/docs/api/openapi/<api>.json or .yaml, with <api> one of v1, kyc, pulse, mcp | The task touches one API and a smaller file fits the context window. |
| API reference | API reference | A person or an agent needs the operations in prose and tables, one page per area. |
Every HTML documentation page also announces its Markdown twin with <link rel="alternate" type="text/markdown"> in the head and a Link response header.
# The same page, two ways.
curl -s https://noxtica.com/docs/getting-started/index.md
curl -s -H 'Accept: text/markdown' https://noxtica.com/docs/getting-started/Follow the integration steps in this order
Each step names the page that holds it. An agent that skips ahead tends to guess; give it one step at a time and let it read the linked page first.
- Choose one protected moment. Pick a signup, login, checkout or recovery step, and decide what happens when no fresh evidence is available. See Getting Started and Integration Flow.
- Register the domain and read its public Site Key. A person does this in Backoffice. See Domains, site keys and the install card.
- Install the browser collector. Load the core script on every page and the extensions after consent. See Install & Browser Runtime and Script attributes and client options.
- Set the consent mode and connect your banner. See Consent modes, GPC and Google Consent Mode and Cookies, storage and consent categories for your site.
- Declare protected actions and trigger the check. The browser hands your backend a request id. See Protected actions: client trigger and server check.
- Create a server key and authenticate. A person creates the key in Backoffice; the server keeps it in its secret store. See API authentication.
- Verify on your server. Redeem the request id or read the device from the backend, and keep the result states separate. See Backend Integration.
- Add identity verification when it is enabled for you. Create a hosted session from the server and read the outcome. Optionally ask first how busy the shared verification capacity is, and read the extracted identity details of a finished verification when your organisation has turned that access on. See Identity verification integration, Check capacity before starting a verification and Read identity details with the API.
- Receive webhooks. Verify the signature of every delivery before you act on it. See API webhooks.
- Handle errors and limits. See API errors and API rate limits.
- Compare before you enforce. Run the policy in observation mode and compare proposed actions with outcomes before any block or challenge. See Getting Started.
- Optional: connect an MCP client. See Connect an MCP client.
Rules an agent must keep
Give the agent these rules in its instructions, next to the task.
Credentials
- Use placeholders in code, prompts and examples:
pk_prod_your_site_key_herefor the public Site Key andsk_prod_your_api_keyfor a server key. Read the real value from an environment variable such asNOXTICA_SERVER_KEYat run time. - Never put a real server key (
sk_…), MCP token (mcp_…), ingestion key, webhook signing secret or Backoffice credential into a prompt, a chat, an issue, a log or a commit. If one reached an agent anyway, revoke it in Backoffice and create a new one. - Keep server credentials out of browser code, URLs, client logs and analytics. The browser holds the public Site Key only.
- Create keys, tokens and webhook endpoints in Backoffice. An agent does not create them, and the documentation does not ask it to.
Consent and people
- Do not grant consent on behalf of a visitor. Call
setConsentonly with the visitor’s own choice, and do not switch a domain to a consent mode that skips the decision just to get past a failing check. The consent mode is a decision for your privacy owner. - Do not create an identity verification session for a person who did not ask for one. The legal basis is recorded by an authorised person in your organisation before a session can be created.
- Read the identity details of a verification only when a tenant administrator turned identity details access on, with a server key created for that permission. The response is personal data: do not log it, cache it or put it in a prompt, and ask for the document number, personal number or machine-readable-zone lines (
?fields=) only when the task needs them. See Read identity details with the API. - Treat a device identifier as a lookup handoff, not as an identity credential.
Results and traffic
- Do not turn a score into a “bot or human” verdict. Read the risk, the confidence and the reasons, and keep
missing,invalid, rate-limited and unavailable results distinct from low risk. - Call only the hosts and operations the documentation and the OpenAPI files name. An operation that is not in them is not part of the public API.
- On HTTP
429, wait for the number of seconds inRetry-After. Do not hard-code a limit: limits depend on the operation and on your account. - Read a session status before you act on an event, and verify the signature of every webhook delivery.
- A write-capable MCP token only plans a change. A person approves each plan in Backoffice; an agent never applies one.
Start from a prompt
Copy a prompt, replace the text in angle brackets, and add the rules above. Each prompt names the pages the agent must read first.
Plan the integration
You are integrating Noxtica into <my application>. Read https://noxtica.com/llms.txt, then
https://noxtica.com/docs/ai-agents/index.md, https://noxtica.com/docs/getting-started/index.md
and https://noxtica.com/docs/integration-flow/index.md.
Propose a plan for one protected moment: <signup | login | checkout | recovery>. List each step in the
order of the documentation, name the page that holds it, say which step a person must do in Backoffice,
and say what the application does when Noxtica returns no fresh evidence.
Do not write code yet. Use the placeholders pk_prod_your_site_key_here and sk_prod_your_api_key.Install the browser collector with consent
Read https://noxtica.com/docs/browser-runtime/index.md and https://noxtica.com/docs/sdk/consent/index.md.
Add the Noxtica core script to every page of <my front-end framework> and load the extensions only after the
visitor consents through <my consent banner>. Use the public Site Key placeholder pk_prod_your_site_key_here.
Show the Content Security Policy change from https://noxtica.com/docs/sdk/csp-and-relay/index.md.
Never call setConsent for a category the visitor has not chosen.Verify on the backend
Read https://noxtica.com/docs/backend-integration/index.md, https://noxtica.com/docs/sdk/protected-actions/index.md
and https://noxtica.com/docs/api/authentication/index.md.
Write the server handler in <my language and framework> that receives the request id from the browser,
redeems it with the server key from the environment variable NOXTICA_SERVER_KEY, and returns one of these
states: received, missing, invalid, rate limited, unavailable. Treat every state except received as "no
fresh evidence", never as low risk. On 429 honour Retry-After. Do not log the key.Create an identity verification session
Read https://noxtica.com/docs/identity-verification-integration/index.md and
https://noxtica.com/docs/api/webhooks/index.md. Use https://noxtica.com/docs/api/openapi/kyc.json for the
request and response shapes.
Write the server code that creates a hosted session with my own opaque customer reference, redirects the
customer to the returned link, and reads the session status. Verify the signature of every
kyc.session.completed delivery and read the status before acting on it. Use the placeholder
sk_prod_your_api_key and never print it.Check capacity before starting a verification
Read https://noxtica.com/docs/identity-verification-integration/index.md, the section "Check capacity
before starting a verification", and https://noxtica.com/docs/api/openapi/kyc.json for the response shape.
Write the server code that reads GET /v1/kyc/load with the server key from the environment variable
NOXTICA_SERVER_KEY, polls no faster than every 10 seconds from one place and shares the answer between
users, and starts a verification only when the recommendation is accept or degraded. On defer, keep the
customer in the application's own queue and retry with backoff. Treat status unknown as "no advice", never
as an error. On 429 honour Retry-After. Do not log the key.Read the identity details of a verification
Read https://noxtica.com/docs/identity-verification-identity-details/index.md and
https://noxtica.com/docs/api/openapi/kyc.json. Write the server code that reads
GET /v1/kyc/verifications/{verificationId}/identity with a server key that carries the permission
read:identity_details, taken from the environment variable NOXTICA_SERVER_KEY. Do not request
the sensitive fields unless the task needs them. Read the redactions list so a withheld value is never
mistaken for a missing one. Treat 403 identity_read_not_enabled as "this organisation has not turned the
access on", not as a retryable error. Do not log, cache or print the response body.Review an integration against the documentation
Read https://noxtica.com/llms-full.txt. Review the Noxtica integration in this repository against it.
Report, per file: a server key reachable from browser code, a consent category granted without a visitor
choice, a result state treated as low risk, a missing Retry-After handling, a webhook handled without
signature verification. Quote the documentation page for each finding and propose the smallest fix.Connect an agent through MCP
An MCP client can read your workspace data with a scoped token. The endpoint is one HTTPS URL that speaks JSON-RPC 2.0; the token is a static bearer token that a person creates in Backoffice under Integrations & API, so configure the client with a custom Authorization header. Start with a read token and call tools/list to see what it may use. See Connect an MCP client and MCP integration.
Common questions
Do I need a key to read the documentation?
No. Every documentation page, llms.txt, llms-full.txt and the OpenAPI files are public. A key is needed only when the integration you build calls a server API.
Can the agent create keys or change settings for me?
No. A person creates keys, tokens, webhook endpoints and consent settings in Backoffice. An MCP token with write access can only plan a change, and a person approves it.
Which is authoritative, the Markdown or the HTML page?
The HTML page at its canonical URL. The Markdown is generated from the same source text, and every Markdown document names its canonical_url and the last_updated date.
Where do I find the exact request and response shapes?
In the OpenAPI files and the API reference. Each reference page names the OpenAPI release it comes from.