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:
- an opaque
tenantId; - a server-only API key with
flows:createandflows:readscopes; - a server-only webhook secret;
- an approved
policyId; - an exact return URL and webhook URL.
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:
- validates Didit's signed callback and timestamp;
- fetches the authoritative decision server-to-server;
- confirms the expected workflow, session, document, liveness, and face-match results;
- extracts exactly one provider-verified legal name; and
- 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:
- Read the raw body before JSON parsing.
- Recompute the HMAC and compare it in constant time.
- Require the locally expected
request_idandpolicy_id. - Apply only allowed monotonic state transitions.
- Make repeated identical events idempotent.
- 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
400: malformed, expired, or internally inconsistent wallet authorization.401: missing/invalid tenant API key or wallet signature.403: requested policy is not enabled for the tenant.404: unknown or cross-tenant request.409: an existingrequest_idwas reused with different identity context.503: required Attesta/provider/key configuration is unavailable.
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
- no Attesta SDK is mandatory;
- no customer smart-contract modification is required;
- no public
canTransact(wallet)lookup is used; - no email or customer account ID is sent to Attesta;
- no second wallet login is introduced.
An official thin adapter may package typed-data construction, URL validation, and webhook verification, but it does not change this wire contract.