Implementation handoff for your developer or AI

Use this page as the implementation brief for the team or AI integrating your product. Register your company and application, then prepare the browser and backend together. Every company follows this same workflow; no preconfigured demonstration customer or site-specific integration is required. When an AI coding agent does the work, also give it the documentation files and repository rules for AI agents.

Start in SHADOW: FingerTrackID assesses and recommends while your product continues to authenticate users and execute its own decisions.

Preparation and activation

The signed assessment API is live in production in shadow mode, and Web SDK collection is deployed there; its end-to-end operation from a customer page is still being measured, and its first real-browser latency figures, from one application, are published (production status). Recommendations only, your product decides. They work for your application once its own inputs are active: the server credential installed with active admission, and the collection domain active for browser collection. Real data needs the applicable security, authentication-isolation, first-party, retention/disposal and operational/recovery proofs. A documentation URL, registered workspace or public key alone provides none of these proofs.

Issued inputs

Obtain the following from actual configuration and the verified onboarding handoff. Mark a missing input as a blocker; do not infer it from an example, another company’s setup or the docs URL.

Input	Where it belongs
Company/application IDs and environment	Integration configuration and support references
Approved private SDK archive, exact version, SHA-256 and SHA-512	Downloaded in the dash (Início › Configuração do SDK, or Integração e saúde › Pacote do SDK Web); verify both hashes against the ones the dash shows before installation
Application public key (pub_app_…)	Browser SDK configuration; a public locator
Exact HTTPS collection origin and allowed site origins	Browser configuration and CSP; the active first-party domain is required
Two exact CNAME names/targets and fresh ownership TXT value	Your DNS provider; publish the issued records and wait for verification
API origin: https://api.fingertrackid.com (also shown in the dash as Endereço da API de risco, step Credencial servidor a servidor)	Backend configuration; origin only, exactly as written, not the OpenAPI example server or a route
UUIDv7 key_id, enabled capabilities, rate and burst limits	Backend configuration; use the issued credential scope
HMAC secret received once in the console, hex encoding	Backend secret manager, straight from the console; never provide the value to an AI
Active policy, qualified release and the request profile in use (v1.1, or v1 and its journeys)	Expected response interpretation and the production feature gate
Named console access and activation confirmation	Human access, mandatory email verification/authenticator and operational record

The standard Web SDK delivery is an approved private archive, downloaded in the dash with the SHA-256 and SHA-512 FingerTrackID recorded for it. Those digests do not imply an independent signature. There is no script installation: script distribution is not enabled (installation).

HMAC material never belongs in this brief or a generated configuration file. FingerTrackID generates the secret and a company administrator or integration manager receives it once in the console and stores it directly in the backend’s secret manager; it is never shown again. While the console shows the credential request as Aguardando você receber o segredo (waiting for you to receive the secret), live signing is blocked; prepare references and synthetic vector tests only.

Managed setup before the implementation

1. In the console’s Início, complete Criar a aplicação with exact site origins such as https://app.yourcompany.com, rather than individual /login or /register URLs.
2. Complete Configurar a coleta web with one of the application’s origins and the owned base domain yourcompany.com. The collector is collect.yourcompany.com, and the SDK collects through it from every allowed origin of the application under that domain (for example https://yourcompany.com and https://www.yourcompany.com); the list is edited later in Integração e saúde › Origens das páginas. The standard cooperative web profile (COOPERATIVE_WEB_SHADOW_V1) produces observation-only MONITOR recommendations; its presence does not demonstrate calibrated fraud detection.
3. Publish the issued DNS records once the platform has prepared the exact first-party binding. Keep both CNAMEs DNS-only. The ownership TXT value does not change: if the platform’s verification window has lapsed, Verificar agora (check now) renews it with the same value, with no request to FingerTrackID and no DNS change.
4. Follow the same request while the platform runs its automatic steps (release, policy, admission and domain); the setup progress says when a step depends on you. Aguardando revisão (waiting for review) is not completed setup; the step is done only when Início shows it as Concluída. If waiting work is cancelled, artifacts already created remain; a cancelled request is not a rollback or a completed integration.
5. Complete Credencial servidor a servidor, receive the secret once with Receber segredo and store it in the backend’s secret manager, then confirm the public key_id, permissions and active production admission. Managed new clients start at 5 requests per second with a burst of 10; the console shows the limit in force and how to raise it (limits).
6. Complete Configuração do SDK once the collection domain is active, and obtain the exact private SDK archive and integration inputs. Prepare code with real issued identifiers and synthetic signing vectors; enable real collection and calls only after the application’s explicit activation confirmation and applicable technical proofs.

Browser SDK activation and signed API activation are confirmed separately. An enabled collector does not waive receiving the credential secret, admission or authentication-isolation/runtime verification for your backend calls.

Keep this brief limited to public IDs, DNS records, hashes, origins and activation references. Do not include private infrastructure plans, cloud credential files, secret locators or HMAC bytes.

Public machine-readable contracts

Download these exact files and preserve their relative directories:

• OpenAPI: assessment.v1.1.yaml (the v1.1 request, accepted in production)
• Request: event-assessment-request.v1.1.schema.json
• Response: event-assessment.v1.1.schema.json
• Synthetic v1.1 requests and responses
• OpenAPI: assessment.v1.yaml
• Request: event-assessment-request.v1.schema.json
• Response: event-assessment.v1.schema.json
• Errors: assessment-problem.v1.schema.json
• Synthetic requests, responses and Problems
• Reference HMAC signer
• Standalone signature self-check
• Normative assessment HMAC vector

The assessment OpenAPI document retains its historical example server, schema identifiers and planned implementation annotation. Those are not issued environment values or proof of deployment; the production API origin is https://api.fingertrackid.com. The public schemas/examples remain the exact contract sources, rather than an approximation. Read authentication, request, response, errors and retry rules together.

Browser integration

1. Verify and install the private SDK package. Initialize it only in browser code, with one SDK copy and one client for the current document/account lifecycle.
2. After any applicable consent, prepare the context on the first intent of the assessed action’s form (focus or pointer-down, never at page load) with createActionContextHelper; it collects again only when the collection would leave the evidence window (60 or 300 seconds) before your margin, when its session ended, after repeated refused lookups, or once per page after a transient limitation; while event contexts are unavailable it adds at most one collection per 300 seconds (stages and reasons); follow the SDK lifecycle. For a login with MFA, the context goes with the MFA submission. If the login redirects to Google or another provider, follow login with Google, OAuth and other redirects. Login, registration and password-recovery pages can be collection locations. In v1.1 each moment your backend assesses gets its own tag (signup, password_recovery…); in v1 they are not additional journeys. Do not read or send form values, passwords, recovery codes or browser-selected identity references to the SDK.
3. For each new business action the backend will assess, take one retained action context at its submit, waiting at most your own ceiling and never aborting the SDK; with SDK 0.3.0 the helper’s take() does this and never rejects. SDK/network/context failure must leave your normal business operation functional.
4. Pass only the captured token and its expiresAt, or null, in your existing authenticated, CSRF-protected business request; the backend sends null if the token is about to expire. Retry the same action with the same handle and captured result, including null. Do not recollect or replace a token to change an existing assessment.
5. Keep the document’s client alive until your backend has answered: closing it before the assessment is stored invalidates the context. Keep it out of page components that unmount at submit, and hold a classic form’s navigation until the context is settled or your ceiling ends; preserve the original deadlines.
6. On logout/account switch, close the client and discard handles before reinitialization. Never delay logout to finish optional collection or persist SDK handles/tokens in storage.
7. Keep your collection origin out of page instrumentation’s trace propagation: an extra request header makes every SDK request fail (tracing headers).

The browser never signs S2S requests or chooses trusted person/account identity. Use the approved SDK interface rather than implementing its transport endpoints yourself.

Backend integration

New integrations use the v1.1 request (event-assessment-request.v1.1): you name each assessed moment with your own tag (login, saque, pix_transfer…), and every tag is assessed the same way. The journey templates suggest tags and call sites for common moments. Production accepts the v1.1 request with your tag.

The v1 request remains supported, unchanged. It has exactly LOGIN, WITHDRAWAL and TRADE, with their actions and closed contexts; do not invent REGISTER or PASSWORD_RECOVERY, or label an unrelated operation LOGIN. An integration already on v1 moves call by call (moving from v1 to v1.1).

For a first login integration, use the tag login (in v1: LOGIN with action: "LOGIN_ATTEMPT") after the backend has completed its real authentication and required MFA, and derives the person’s subject_ref and the account’s account_ref as stable keyed pseudonyms (person and account references). Send it right away: the browser context of that login must be stored before its expiresAt. A provisional session or OTP request is not completed authentication. Preserve the existing login response even if FingerTrackID is unavailable.

For every logical assessment:

1. Derive occurred_at, identity references (the same subject_ref and account_ref pair for the same person and account on every call), external_event_id and idempotency_key on the backend. Never accept browser values as authority for those fields.
2. Validate the closed request and serialize it once. Retain the exact original bytes and token, including null, with the logical operation.
3. For each transport attempt, generate a new UUIDv7 request_id, current timestamp and signature over those same bytes. Decode the 64-character hex key to its 32 bytes before HMAC.
4. Validate the returned assessment or Problem. Check the expected event and its tag (v1.1) or journey (v1), and preserve the returned policy/release/recommendation fields.
5. Follow the retry matrix. An unknown result is reconciled by the same POST and original bytes; a definitive 410 never triggers regenerated operation IDs.

A missing context means missing browser evidence. It does not guarantee INCONCLUSIVE, 201, a score or success. trust_score: null is no score, never a default of 0 or 100. The customer decides and executes the action; FingerTrackID never applies a block in your product.

Feedback and console verification

When your credential has the required active capabilities, use the customer-action and outcome contracts to report your actual decision and later evidence. A block, cancellation or score is not fraud confirmation. Do not declare alignment that FingerTrackID must derive, or overwrite historical truth with the latest policy.

Use the console to inspect Acessos (accesses), Integração e saúde (integration and health), Configuração de risco (risk configuration), Auditoria (audit) and Uso (usage) according to your role. Usage is an estimate from immutable records, not an invoice or a fraud-accuracy metric.

Review and activation

Show your integration diff and synthetic checks for the signature vector, schema validation, duplicate/retry behavior, unknown/expired results, SDK initialization/synchronous-context failure, unavailable network/context, logout/account switch and correct server authentication placement. Demonstrate that your product remains functional when the integration is disabled or unavailable.

FingerTrackID confirms the actual inputs, domain, credential installation, active admission, policy/release and applicable proofs before enabling real traffic. Keep request/operation IDs, correlation IDs, timestamps and public error codes for support. Never log tokens, secrets, cookies, personal data or full payloads.

Before going live, read the integration guidance: always send the assessment (with null when there is no context), fail open with visible errors, evaluate the shadow period with feedback and test in production without a sandbox. For your privacy policy, see data collected and processing.

Finish with the integration checklist.