Hosted approval

Your backend signs an identity assertion, creates a five-minute approval session, and redirects the authenticated end user to Attesso. The assertion and approval URL are bearer secrets and must not be logged.

Configure approval trust

Before an approval session can be opened, register your identity provider in the dashboard (per environment: test and live). The API verifies the signed assertion it receives against these three values and refuses anything else.

Field	What to provide
Identity issuer	An HTTPS URL that exactly matches the `iss` claim on the assertion you sign
Exact return origin	Where the browser returns after the passkey ceremony — a bare origin (scheme + host + optional port, no path, no query, no fragment)
ES256 public JWKs	One or two `ES256`/`P-256` public JSON Web Keys (no private `d` value)

Return to the origin you registered exactly: https://app.example.com is allowed, and so is https://app.example.com/approval-return — only the origin (scheme + host + port) is compared, so a path is fine. Generate an ES256/P-256 key pair on your own infrastructure and register only its public key:

# Private key (keep server-side, never share)
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 \
  -out identity.pem

Derive the public JWK from that PEM with the same jose tooling used to sign assertions (see below):

import { readFile } from 'node:fs/promises';
import { importPKCS8 } from 'jose';

const key = await importPKCS8(await readFile('identity.pem', 'utf8'), 'ES256');
const { kty, crv, x, y } = await crypto.subtle.exportKey('jwk', key); // add use:"sig", alg:"ES256", kid

The registered JWK must be the public key that corresponds to the exact private key you sign with. Give it a stable kid and reference that same kid in the assertion header.

Identity assertion contract

The compact JWS must use:

Field	Required value
`typ`	`attesso-identity+jwt`
`alg`	`ES256`
`kid`	An active registered key ID
`iss`	Your exact registered issuer
`sub`	The Mandate’s exact `subject_reference`
`aud`	`urn:attesso:approval:test:v1` for a test key
`iat`, `exp`	Integer seconds; lifetime no longer than five minutes
`jti`	Unique for this assertion

Attesso accepts only the configured issuer and public JWKs. It never fetches a key URL from the token and never receives your private key.

TypeScript

Install jose, load the key from your secret store, and keep the resulting token in server memory only.

import { randomUUID } from 'node:crypto';
import { readFile } from 'node:fs/promises';
import { importPKCS8, SignJWT } from 'jose';

const privateKey = await importPKCS8(
  await readFile(process.env.IDENTITY_PRIVATE_KEY_PATH!, 'utf8'),
  'ES256',
);
const now = Math.floor(Date.now() / 1000);

const identityAssertion = await new SignJWT({})
  .setProtectedHeader({
    typ: 'attesso-identity+jwt',
    alg: 'ES256',
    kid: process.env.IDENTITY_KEY_ID!,
  })
  .setIssuer(process.env.IDENTITY_ISSUER!)
  .setSubject(mandateSubjectReference)
  .setAudience('urn:attesso:approval:test:v1')
  .setIssuedAt(now)
  .setExpirationTime(now + 300)
  .setJti(randomUUID())
  .sign(privateKey);

Python

Install PyJWT[crypto] and apply the same fixed algorithm and claims.

import os
import time
import uuid
from pathlib import Path

import jwt

now = int(time.time())
private_key = Path(os.environ["IDENTITY_PRIVATE_KEY_PATH"]).read_text()

identity_assertion = jwt.encode(
    {
        "iss": os.environ["IDENTITY_ISSUER"],
        "sub": mandate_subject_reference,
        "aud": "urn:attesso:approval:test:v1",
        "iat": now,
        "exp": now + 300,
        "jti": str(uuid.uuid4()),
    },
    private_key,
    algorithm="ES256",
    headers={
        "typ": "attesso-identity+jwt",
        "kid": os.environ["IDENTITY_KEY_ID"],
    },
)

Create and handle the session

Send the assertion with an exact pre-registered return origin and unpredictable return_state to POST /v1/mandates/{mandate_id}/approval-sessions.

approval_url is a five-minute, single-use bearer URL. Redirect to it without analytics, logging, browser storage, or email.

After the passkey ceremony, Attesso returns the browser to your configured URL with an approval result in the fragment. Validate attesso_state, then retrieve the Mandate with your backend API key. The redirect is not proof of approval; the server-to-server Mandate state is authoritative. If a session expires, reauthenticate the user and create a new session. Never attempt to recover or reuse the old approval URL.

Start

Core model

Integration guides

Reference

Hosted approval

Configure approval trust

Identity assertion contract

TypeScript

Python

Create and handle the session

​Configure approval trust

​Identity assertion contract

​TypeScript

​Python

​Create and handle the session

Configure approval trust

Identity assertion contract

TypeScript

Python

Create and handle the session