Developers

Not yet checked on the product

This chapter was written from the product's source code and has not yet been checked by a person on a running Cogneris. If what you see on screen differs, the screen is right — please tell your Cogneris contact so the chapter can be corrected.

The Developers area holds what your own systems need to call the Cogneris API and to be called back by it: API keys, webhook endpoints, and the logs of API calls and webhook deliveries. The API itself is described in the developer portal.

How to get here	Vision menu › Developers › API Keys, Webhook Endpoints, API Request Logs or Webhook Request Logs. Opening Developers itself lands on API Keys.
Who can use it	Tenant administrators: the customer-admin and customer-tech profiles, and Cogneris operators (cogneris-admin, cogneris-tech) inside their own company. The services refuse every other member. When a list cannot be loaded — including when the service refuses a member without access — the screen says so instead of showing an empty list.
Content status	From source; not observed (vision-fe 0b724a0 + cogneris-vision-fe#192, vision-be fce7fcc + cogneris-vision-be#504, platform-be 166c01e, billing-be 12ce77c, 2026-10-22)

API Keys

API Keys — Manage keys used to authenticate against the Cogneris API. An API key is a secret your server sends with each API call. Each key belongs to one application and one environment:

• Sandbox keys start with xtkt_test_ and reach only sandbox data.
• Production keys start with xtkt_live_ and act on real data.

After the prefix, a key has 43 random letters and digits. Cogneris stores only a hash of the key; the full key is shown once, when it is created.

The list does not include developer tokens for the MCP server; those are managed on the MCP page.

Fields

The list:

Field	What it shows	Format
Name	The name given at creation.	Text
Key	The key, masked: its prefix, eight dots and its last four characters.	For example xtkt_live_••••••••a1B2
Application	The application the key belongs to.	Text, or -
Environment	Sandbox or Production.	Badge
Access	The key's scopes, or Full access (highlighted) for a key that can do everything — including every key created before access could be chosen.	Comma-separated scope names, or badge
Expires	The date the key stops working, or Never (highlighted) for a key with no expiry.	Date in your language's format, or badge
Created	Creation date.	Date in your language's format
Last used	Date the key was last used, or Never.	Date in your language's format
Status	Active or Revoked. Revoked keys stay in the list, greyed out.	Badge
Actions	Revoke, on active keys only.	—

The New API Key dialog:

Field	What it does	Required	Format / values	Default	Validation messages
Name	A label for the key. Hint: A short description so you can identify the key later.	Yes	Up to 120 characters. Placeholder e.g. Production backend.	Empty	Generate key stays disabled while empty.
Application	The application the key is minted in.	Yes, when shown	Your company's applications	The first application	—
Environment	Where the key works. Hint: Sandbox keys start with xtkt_test_ and only reach sandbox data. Production keys start with xtkt_live_ and touch real data.	Yes, when shown	Sandbox, Production	Sandbox	—
Access	What the key can do. Hint: Pick the smallest access your integration needs. Full access is available, but never the default. Each choice explains itself below the field.	Yes	See the table below	None — placeholder Choose what this key can do	Generate key stays disabled until an access is chosen.
Scopes	Shown only for Custom: one checkbox per scope. Hint: Tick each scope the key needs.	Yes, for Custom	Scope names, for example workflows.read	None ticked	Generate key stays disabled while no scope is ticked.
Expires after	How long the key works. Hint: Every key expires. Create a new key before this one stops working.	Yes	30, 90, 180 or 365 days	90 days	—

The Access choices:

Choice	Scopes the key gets
Extraction	classifiers.read, classifiers.write, playground.run — classifiers and the playground.
Documents	ecm.documents.read, ecm.documents.write, ecm.folders.read, ecm.folders.write, ecm.search.read — the Document Center.
Portal	portal.forms.read, portal.magiclinks.write — read forms and send magic links.
Workflow	workflows.read, workflows.write — read workflows and runs, publish and start runs.
Read only	classifiers.read, ecm.documents.read, ecm.folders.read, ecm.search.read, portal.forms.read, workflows.read — nothing is changed.
Custom	The scopes you tick. Besides the ones above, webhooks.manage (webhook endpoints), apikeys.manage (create and revoke keys through the API, only with scopes the key itself has) and builder.run (Build AI, which spends credits).
Full access	* — everything the API allows, including managing keys and Build AI. Use it only when no narrower choice fits.

When the applications cannot be loaded, Application and Environment are not shown and the dialog says Applications could not be loaded; the key will be created in the default production environment.

A key created on this screen always has the access you chose and always expires; after the expiry date the service refuses it. Revoking stops it earlier. Developer-token scopes (mcp.read, mcp.write) are not offered here — those keys are created on the MCP page.

Keys created before this choice existed have Full access and Never expire. While any of them is still active, the list says … active key(s) have full access or never expire. Create a replacement with limited access and an expiry, then revoke the old key. Nothing is revoked for you: create the replacement, move your integration to it, then Revoke the old key.

Buttons and actions

Button	What happens	Who	Reversible?
New API Key	Opens the New API Key dialog.	Tenant administrators	—
Generate key (Generating... while it runs)	Creates the key and shows it once, with Save this key now — you will not see it again., the environment badge and the application name.	Tenant administrators	Revoke the key to undo.
Copy / Copied!	Copies the new key to the clipboard.	—	—
Done	Closes the dialog. The full key cannot be shown again.	—	—
Cancel	Closes the dialog without creating a key.	—	—
Revoke	Asks Revoke API key — After revoking, … can no longer be used to authenticate. This operation is irreversible. — then Yes, revoke revokes the key and records who revoked it.	Tenant administrators	No

Common problems

Message	Cause	What to do
No API keys yet. Create your first to start using the API.	No integration key exists — or the list could not be loaded (for example your profile is not a tenant administrator), which the screen does not distinguish.	Check your profile with an administrator.
Applications could not be loaded; the key will be created in the default production environment.	The applications service did not answer.	Close the dialog and try later if you need a sandbox key.
The dialog stays open after Generate key with the service's reason, or The key could not be created. Please try again.	The service refused the request or did not answer.	Read the reason; try again; check that you are a tenant administrator.
The key could not be revoked. Please try again. (or the service's reason)	Revoking failed; the key is still active.	Try again.
Couldn't load your API keys. Please try again.	The list could not be read.	Reload the page.
Loading keys...	The list is loading.	—
… active key(s) have full access or never expire. …	At least one active key was created with full access or without an expiry.	Create a replacement with the access your integration needs, switch to it, then revoke the old key.

Webhook Endpoints

Webhook Endpoints — Send HTTPS callbacks to your own servers when operations complete. An endpoint is a URL on your server that Cogneris calls with a JSON message when one of the chosen events happens.

Endpoints created on this screen receive the events of your production environment. Sandbox endpoints are created through the API with a sandbox key and do not appear here.

Fields

The list:

Field	What it shows	Format
Name	The endpoint name.	Text
URL	The endpoint URL.	Text
Events	The subscribed events: the first two, then + and the count of the others.	For example extract.processed, extract.failed +2
Status	Active or Inactive. Inactive endpoints are greyed out and receive nothing.	Badge
Created	Creation date and time.	Date and time
Actions	Edit, Delete.	—

The Create webhook endpoint / Edit webhook endpoint dialog opens with All endpoints must be HTTPS.

Field	What it does	Required	Format / values	Default	Validation messages
Endpoint name	A label for the endpoint.	Yes	Up to 100 characters. Placeholder e.g. Service X webhook.	Empty	Name is required.
Endpoint URL	Where Cogneris sends the events. The service also refuses URLs that point to private, loopback or link-local addresses, and checks the address again at every delivery.	Yes	Absolute https:// URL, up to 500 characters. Placeholder https://hook.yourdomain.com/example.	Empty	URL must be an absolute HTTPS address.
Select events to subscribe to	The events this endpoint receives. Hint: Choose at least one event.	Yes	See Events.	None	Select at least one event.
Advanced options › Custom request headers (optional)	Headers added to every request to this endpoint, for example your own authentication header. Hint: Sent with every request to this endpoint. One row per header. Rows with an empty Header name are dropped. Stored encrypted.	No	Header name, Value pairs	None	—
Advanced options › Override request body (optional)	Replaces the event message with this text. Hint: If set, replaces the default event payload sent to the endpoint. Keep blank to receive the default JSON. The text is sent as is, as application/json, and the signature is computed over it. Stored encrypted.	No	Text	Empty (default JSON)	—
Active	Shown only when editing. Unticked, the endpoint stops receiving events but is kept.	—	Checkbox	Ticked	—

Advanced options opens by itself when the endpoint being edited already has headers or a body.

Events

Event	Sent when
extract.processed, extract.failed	An extraction finishes or fails.
zeroshot.processed, zeroshot.failed	A zero-shot extraction finishes or fails.
crop.processed, crop.failed	A crop operation finishes or fails.
split.processed, split.failed	A document split finishes or fails.
classifier.processed, classifier.failed	A classification finishes or fails.
redaction.processed, redaction.failed	A redaction job finishes or fails.
facematch.processed, facematch.failed	A face-match job finishes or fails.

Signing secret

When an endpoint is created, the dialog shows its Signing secret once, with Save this signing secret now — you will not see it again. The secret starts with whsec_ followed by 64 hexadecimal characters.

Changing the Endpoint URL of an existing endpoint replaces the secret: after Save endpoint the dialog shows the new secret, once. Changing anything else keeps the secret. This screen has no other way to see or replace a secret.

How each request is signed

Every delivery is an HTTPS POST with these headers:

Header	Value
X-Xtrakt-Signature	The signature, in the format below.
X-Xtrakt-Event	The event name, for example extract.processed.
X-Xtrakt-Delivery	An ID that stays the same across every attempt of the same event at the same endpoint. Use it to ignore duplicates.
X-Xtrakt-Delivery-Attempt	The attempt number, starting at 1.
Your custom headers	As configured.

The signature header has this format, where T is the time of the attempt in Unix seconds and HEX is the lowercase hexadecimal HMAC-SHA256 of T, a dot and the exact request body, keyed with the whole signing secret (including whsec_):

X-Xtrakt-Signature: t=T,v1=HEX
signed string:      T.BODY

To verify a request, recompute the HMAC over the timestamp, a dot and the raw body as received, and compare it with v1 in constant time. The signature is rebuilt at each attempt, with a new timestamp.

The secret's description in the dialog names the same header: Use this secret to verify the X-Xtrakt-Signature header on incoming webhook requests (HMAC-SHA256 over <timestamp>.<body>).

Delivery and retries

• Only Active endpoints subscribed to the event, in the event's environment, receive it.
• Your server must answer within 10 seconds. Redirects are not followed. Any 2xx answer counts as delivered.
• A delivery that fails with a 5xx, 408 or 429 answer, a timeout or a connection error is tried again, with a growing delay between 10 seconds and 10 minutes, up to 5 attempts in all. Any other 4xx answer is final and not retried.
• Every attempt is listed in Webhook Request Logs.

Buttons and actions

Button	What happens	Who	Reversible?
+ New endpoint	Opens Create webhook endpoint.	Tenant administrators	—
+ Add header	Adds a header row. × removes one.	—	—
Save endpoint (Saving... while it runs)	Checks the fields, then creates or updates the endpoint. On create, and on an update that changed the URL, shows the signing secret.	Tenant administrators	Yes — edit again.
Copy / Copied!	Copies the signing secret.	—	—
Done	Closes the secret panel. The secret cannot be shown again.	—	—
Cancel	Closes the dialog without saving.	—	—
Edit	Opens Edit webhook endpoint with the endpoint's values.	Tenant administrators	—
Delete	Asks Delete endpoint — Endpoint … will stop receiving events. This operation is irreversible. — then Yes, delete removes it.	Tenant administrators	No

This screen has no test button. A test event can be sent through the API (see the developer portal) or from an editor connected to the MCP server.

Common problems

Message	Cause	What to do
Something went wrong. Please try again.	The service refused the endpoint — for example the URL points to a private or local address — or the request failed.	Use a public HTTPS URL and save again.
No endpoints yet. Create your first to start receiving events.	No endpoint exists — or the list could not be loaded, which the screen does not distinguish.	Check that you are a tenant administrator.
Your server rejects every request as unsigned	It looks for a header other than X-Xtrakt-Signature — for example X-Cogneris-Signature, which earlier versions of the dialog named.	Read X-Xtrakt-Signature (see How each request is signed).
Signatures do not match	The body was re-serialised before hashing, or the URL was changed and the old secret is still in use.	Hash the raw body; use the secret shown after the last URL change.
Loading endpoints...	The list is loading.	—

API Request Logs

API Request Logs — Every API call billed to this tenant. A read-only list of the calls your company made to the Cogneris API, newest first.

Fields

Field	What it does	Format / values
Environment (filter)	Shows only the calls of one environment. Applied by the service.	All environments, Sandbox, Production, Unknown origin (calls with no recorded environment)
Created at	When the call was made.	Date and time
IP	The address the call came from.	Text, or -
Duration	How long the call took.	Milliseconds
Environment	The environment of the key used.	Sandbox, Production or Unknown origin badge

View details opens Call details: Created at, Duration, IP, Environment, and Response — the details the service recorded for the call, as formatted JSON.

Buttons and actions

Button	What happens	Who	Reversible?
Refresh (Loading... while it runs)	Loads the list again.	Tenant administrators	—
View details	Opens Call details. Close it with ✕ or by clicking outside.	Tenant administrators	—

Common problems

Message	Cause	What to do
Could not load API logs. Please try again. (with the HTTP status when there is one)	The list could not be read. 403 means your profile is not a tenant administrator.	Use Refresh, or ask an administrator.
No API calls yet.	No call matches the filter.	Choose All environments.

Webhook Request Logs

Webhook Request Logs — Every webhook delivery billed to this tenant. A read-only list of the webhook deliveries Cogneris made to your endpoints, one row per attempt.

Fields

Field	What it does	Format
Created at	When the delivery was made.	Date and time
Webhook	The webhook the delivery belongs to, as the service recorded it.	Text, or -
Event	The event delivered.	Event name

View details — shown on rows that have a delivery record — opens Delivery details:

Field	What it shows
Success / Failure	Whether the endpoint answered with a 2xx.
HTTP status	Your server's status code, or - when it did not answer.
Duration	Time to the answer, in milliseconds.
Attempt	The attempt number (see Delivery and retries).
URL	The URL called.
Event	The event name.
Error message	Shown when the attempt failed without an answer or reached the attempt limit, for example webhook_timeout, webhook_dispatch_failed or webhook_retries_exhausted.
Request body	The JSON sent.
Response body	What your server answered, or -.

Buttons and actions

Button	What happens	Who	Reversible?
Refresh (Loading... while it runs)	Loads the list again.	Tenant administrators	—
View details	Opens Delivery details. Close it with ✕ or by clicking outside.	Tenant administrators	—

Common problems

Message	Cause	What to do
Unable to load delivery details.	The delivery record could not be read.	Close the dialog and try again.
No webhook deliveries yet.	No delivery was made — or the list could not be loaded, which the screen does not distinguish.	Use Refresh; check that you are a tenant administrator.

Related

• MCP — developer tokens and connecting an editor.
• Vision administration overview

---

Last reviewed 2026-10-23 · Version 1.0.0 · Owner: product-documentation