Consuming Attesta

Product boundary

Product direction reaffirmed 2026-09-19: Attesta is an independent verification product for external companies and ecosystem dapps. BrazilCarbon is one customer of its shared tenant integration. The initial launch is free/partner-only by owner decision on 2026-09-20. Paid billing and billable-event selection are deferred.

Preserve tenant isolation, customer-specific credentials and callbacks, and policy-and-chain-scoped credential reuse when evolving this integration. Runtime federation and KMS access are operated by Attesta; hosted customers do not need Google credentials or access to its signing keys. Optional protocol publication remains subject to the customer's governed contract integration. Potential usage metering must respect the existing data-minimization boundary; this product direction does not establish billing or production readiness.

Release scope

Internal staging selects Didit identity verification only as of 2026-09-19: document, liveness and face match, with no AML/sanctions claim. Its separate policy ID is 0x6d2fba2df69407c6f110b55dcb0e50a5c6c5789290eddaf4f42a9592629e0274 (KYC_IDENTITY_V1). Credentials may be reused only within their existing policy and chain scope. See Didit integration for the required configuration. The owner executed the Fuji adapter policy update on 2026-09-20; independent readback confirms required claims 1 and Safe nonce 2. This selection does not establish production readiness.

The supported integration is a hosted REST flow. A customer does not need to modify a smart contract and does not query a public wallet KYC registry. Protocols with an existing Attesta adapter may opt into the explicit, server-only post-approval publication step described below.

Publisher operators can use the existing wallet signer or the dedicated Google HSM integration in ATTESTA_GOOGLE_KMS.md. The managed signer still requires configured runtime identity and governed contract binding; creating a cloud key alone does not activate on-chain publication.

From the customer's perspective the protocol is:

existing authenticated session
        |
        +-- wallet signs one short-lived binding
        |
customer backend -- POST /v1/flows --> Attesta hosted page --> Didit if needed
        ^                                      |
        +----------- signed webhook -----------+

approved protocol flow -- POST /v1/flows/{requestId}/attestation --> adapter

The customer calls one Attesta creation endpoint. The hosted page's exchange, session, provider-launch, and polling routes are Attesta internals and are not part of the customer API.

Register your app without a portal

The release candidate adds REST-only self-service. These new endpoints require the candidate's additive schema migration and API deployment; their presence in this guide does not mean the previous staging image exposes them yet.

One-time onboarding uses your app owner's EOA wallet. Request a challenge, sign the returned SIWE message using your existing wallet, and submit that signature from your backend. No transaction, gas, Attesta portal, provider account or Google credential is required. Smart-contract owner wallets (EIP-1271) are not supported in this initial owner-authentication boundary.

POST /v1/tenants/challenges
Content-Type: application/json
{
  "owner_wallet": "0x1234567890abcdef1234567890abcdef12345678",
  "chain_id": 43113,
  "action": "register",
  "app": {
    "app_id": "my-rwa-app",
    "display_name": "My RWA App",
    "return_url": "https://app.example/verification-complete",
    "webhook_url": "https://api.example/attesta-result"
  }
}

The 201 response contains challenge_id, message and expires_at. Check the Attesta domain, chain and requested action, then sign the exact UTF-8 message with the wallet's personal_sign/signMessage method. Challenges expire after five minutes and bind the complete app configuration and configured policy.

POST /v1/tenants/actions
Content-Type: application/json
{"challenge_id":"<returned challenge_id>","signature":"0x<65-byte signature>"}

The 201 response returns tenant (including id, app_id, URLs and policy_id), api_key, webhook_secret and scopes. Store both secrets in your server's secret store immediately. Never put them in browser storage, URLs or logs. The response is Cache-Control: no-store; a successful challenge cannot be replayed to retrieve credentials. The API key has only flows:create and flows:read scopes and cannot manage tenants or call administrator routes.

app_id is a stable lowercase identifier, unique to that owner wallet. Omit webhook_url for a polling-only integration. Return/callback URLs must be exact public HTTPS URLs on port 443 without credentials, query strings or fragments. Callbacks reject private/link-local DNS destinations, pin the checked IP for delivery and never follow redirects. Loopback HTTP is permitted only in isolated development/test environments.

Every management action uses the same challenge → signature → action sequence:

action Extra challenge fields Result
list None Your app IDs/configuration, without secrets
configure tenant_id, complete app Updated name/URLs; app_id is immutable
rotate_api_key tenant_id One new scoped key; all old keys immediately revoked
revoke_api_keys tenant_id All active verification keys revoked
rotate_webhook_secret tenant_id One new callback secret; coordinate receiver update

A fresh owner signature is required each time; no browser session or API-key management authority is created. Losing a successful response does not require re-registering: use list, then rotate_api_key or rotate_webhook_secret. Registration of the same owner/app ID returns 409. Expired or invalid proofs return 401, used challenges return 409, and another owner's app returns 404. Respect 429 and Retry-After. Existing operator-provisioned tenants are preserved and are not automatically claimed by any wallet; scripts/tenant.py remains an operator recovery tool.

After this one-time setup, the recurring integration has three steps: obtain the existing wallet binding and create a flow, open its hosted URL, then consume the signed result or poll status. On-chain publication is optional and separate.

Provisioned values

Attesta provisions each customer with:

Tenant records are database-backed. A new tenant or rotated credential becomes active without an Attesta restart or a per-tenant environment-variable edit. The human-readable tenant name is control-plane metadata only; the opaque ID is hashed into wallet authorizations and the display name is never copied into a verification record or webhook.

1. Create the wallet binding

Generate a cryptographically random 32-byte requestId and persist this local mapping before calling Attesta:

requestId -> your account/profile and expected wallet

Build this EIP-712 message from the already authenticated account:

Domain
  name:    Attesta KYC
  version: 1
  chainId: <configured EVM chain>

Primary type: AttestaHostedKycBinding
  bytes32 protocolVersion
  bytes32 tenantIdHash
  bytes32 requestId
  bytes32 policyId
  uint8   authorizationMode
  address signer
  address businessWallet
  uint256 chainId
  uint64  deadline

Derived constants:

protocolVersion = keccak256("AttestaHostedKycBinding/v1")
tenantIdHash     = keccak256(utf8(lowercase opaque tenantId))

Authorization modes:

Value JSON name Rule
1 direct_wallet signer == businessWallet
2 tenant_mapped_account the established authentication signer authorizes the business wallet recorded by the tenant's standardized account system

Do not accept the wallet, tenant, policy, chain, or return URL from unauthenticated browser input. Do not start another wallet login. Use the same authenticated wallet adapter and account-to-business-wallet mapping already used by the application.

Set deadline no more than the configured authorization TTL into the future (five minutes by default). The user signs this typed request once.

2. Call the one creation endpoint

POST /v1/flows
X-API-Key: <server-only tenant key>
Content-Type: application/json
{
  "full_name": "Joana Silva",
  "request_id": "0x1111111111111111111111111111111111111111111111111111111111111111",
  "policy_id": "0x6d2fba2df69407c6f110b55dcb0e50a5c6c5789290eddaf4f42a9592629e0274",
  "chain_id": 43113,
  "authorization_mode": "direct_wallet",
  "signer_address": "0x1234567890abcdef1234567890abcdef12345678",
  "wallet_address": "0x1234567890abcdef1234567890abcdef12345678",
  "deadline": 1800000000,
  "signature": "0x<65-byte-signature>"
}

For a company representative, optionally add this object to the same request:

"company": {
  "company_name": "Example Forestry",
  "registry_number": "REG-123",
  "incorporation_date": "2020-01-01"
}

Omit company for individual-only verification. Company details are immutable for a given request ID. Reopening a flow uses that same ID and does not trigger another company submission. There is no separate company-check tenant API. Attesta owns the provider credentials, callback, reconciliation and decision history; BrazilCarbon uses this same tenant contract.

Company AML is disabled for now. KYC_SHUFTI_MODE=off is the default, even when credentials are configured. With screening off, new flows verify only identity through Didit, including company representatives. Optional company metadata does not start or block screening and is not stored as an AML case. The resulting approval is identity approval only, never company AML clearance. Existing checks started under an enabled policy are not silently waived. Shufti calls, including reconciliation, require explicit live configuration. Didit's company AML is also paid, currently $0.20 per screen, outside its free KYC allowance (provider pricing, checked 2026-09-20). No alternative paid integration is activated.

For isolated local QA only, the operator can set KYC_SHUFTI_MODE=sandbox and KYC_SHUFTI_SANDBOX_RESULT to clear, pending, review_required, rejected, or error. This requires a local chain (31337/31338/31339), Didit sandbox and on-chain publication off. It performs no network screening. The hosted screen labels simulation; the durable result is simulated_*. Even simulated clear remains in_review, cannot be manually promoted, and issues no reusable credential or on-chain approval. Staging/production reject this mode.

When live company screening is explicitly enabled, a requested company check must finish before the common flow is approved. Potential matches require the existing administrative review; missing evidence, provider failures, disabled checks and simulated results cannot be approved by that review. Company legal details and digest-only event history are private Attesta records. Raw provider responses are not retained. An unstarted expired flow deletes its temporary company details along with the handoff.

Attesta returns exactly:

{
  "flow_id": "7c4ff7ccda51463f95fbfbdc438e5ec8",
  "hosted_url": "https://kyc.example/verify/<one-time-token>",
  "expires_at": "2026-08-10T12:00:00Z"
}

Validate the configured HTTPS origin and /verify/ path, then open hosted_url. Do not parse identity or authority from the token. It is a short-lived browser capability; only its digest is stored, and its exchange is atomic and one-time.

This request intentionally contains no email, phone, CPF, document number, external account reference, or customer account ID. The wallet and signature are transient authorization inputs. Attesta verifies them and persists only a keyed wallet tag.

3. First verification versus reuse

For a wallet with no active credential under the requested policy and chain, the hosted page starts Didit. Didit collects the document, selfie, liveness, and face-match evidence on its origin.

Attesta approves only after it:

  1. validates Didit's signed callback and timestamp;
  2. fetches the authoritative decision server-to-server;
  3. confirms the expected workflow, session, document, liveness, and face-match results;
  4. extracts exactly one provider-verified legal name; and
  5. if live business screening is enabled and the tenant supplied company details, completes that check within the same case. With screening off, company representatives complete identity KYC only. Business AML does not establish individual sanctions clearance.

A missing or ambiguous verified identity does not pass automatically; it enters review. For a successful first verification, the authenticated status response delivers the verified name temporarily so the tenant can correct its local display name. The hosted browser and webhook never receive it.

For a matching active private credential, Attesta skips Didit and immediately issues the new tenant's opaque grant. This works across approved tenants because the wallet tag is policy-scoped, not tenant-scoped. The new tenant learns only the result for its own requestId; it cannot list the other tenants or query a public wallet status.

4. Consume the signed webhook

Attesta signs the exact raw JSON body with the tenant webhook secret:

X-KYC-Signature = hex(HMAC-SHA256(webhookSecret, rawBody))

Example:

{
  "event": "case.approved",
  "data": {
    "request_id": "0x1111111111111111111111111111111111111111111111111111111111111111",
    "policy_id": "0x525ddd7695cee6e297fc4ac870b49aeff1aeeaac3efa60b1ac00b5f9d9f89e2f",
    "status": "approved",
    "credential_expires_at": 1810000000
  }
}

Receiver requirements:

  1. Read the raw body before JSON parsing.
  2. Recompute the HMAC and compare it in constant time.
  3. Require the locally expected request_id and policy_id.
  4. Apply only allowed monotonic state transitions.
  5. Make repeated identical events idempotent.
  6. Return success only after the local request state is durable.

Events are durably queued by Attesta and retried with a worker lease and bounded backoff. Approval, rejection, expiry, and revocation use the same minimal data shape. When a credential is suspended, every tenant grant created from it gets its own case.suspended event with only that tenant's request ID.

5. Optional status reconciliation

If a webhook is delayed, query the same opaque request:

GET /v1/flows/0x<request-id>
X-API-Key: <server-only tenant key>
{
  "request_id": "0x<request-id>",
  "status": "approved",
  "credential_expires_at": 1810000000,
  "verified_full_name": "Maria Souza"
}

The API key is tenant-scoped. A different tenant receives 404 even if it guesses the request ID. verified_full_name is present only for the bounded post-Didit delivery window and is then null; credential reuse also returns null because no new document name was processed.

Status handling

Status Customer behavior
created hosted flow exists but verification has not started
pending / in_review keep access restricted and show the hosted/review state
approved enable the customer's KYC-dependent application behavior until expiry
rejected keep access restricted; show reason-safe retry/support copy
suspended remove KYC-dependent access and allow a new verification when policy permits

The customer remains authoritative for its own account state. Browser popup messages are refresh hints only; they must never mark an account approved.

Optional protocol-attestation step

Only after the authenticated status is approved, a protocol backend may call:

POST /v1/flows/0x<request-id>/attestation
X-API-Key: <server-only tenant key>
Content-Type: application/json

{"wallet_address":"0x<expected-business-wallet>"}

Attesta derives the wallet tag again from the flow's policy and chain and compares it to the approved private credential. Therefore the caller cannot substitute a different wallet. Publication is idempotent: the signed attestation is persisted before the chain side effect, and retries publish or verify those same values. The response is approved only after the registry write and configured adapter view are confirmed.

Data retained by Attesta

After terminal processing, the reusable credential contains:

policyId
chainId
HMAC wallet tag + key version
active/revoked/expired status
expiry
opaque revocation handle
timestamps

The tenant grant contains:

opaque tenant ID
requestId
policyId
credential reference
grant status and expiry
timestamps

It contains no plaintext wallet, name, email, customer account reference, signature, CPF, document, selfie, or provider report. Temporary identity and provider-session data exist only while the first KYC is being reconciled and are erased after the terminal result is queued. An abandoned request that never starts provider verification is deleted after its launch and hosted session capabilities have both expired.

The optional protocol-attestation step has a distinct, explicit privacy boundary: its claim subject is the business wallet, which is retained in the attestation record and published on-chain. The private hosted credential and tenant grant remain pseudonymous.

The HMAC wallet tag is pseudonymous, not anonymous. Its security depends on a secret MAC key and restricted access to the MAC operation. Didit necessarily processes the user's evidence while performing KYC. These limits must be stated in privacy notices and the data-processing agreement.

Errors and retries

Retry 503 with bounded backoff. Repeating an identical unstarted request ID rotates its one-time launch capability; changing any authority-bearing field for that request fails closed.

What is not required

An official thin adapter may package typed-data construction, URL validation, and webhook verification, but it does not change this wire contract.