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. On the test plane, the quickstart script provisions the same trust on its first run through PUT /v1/approval-trust. Live has no provisioning endpoint; use the dashboard.

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: an origin (scheme + host + optional port). The registered value has no path, query, or fragment; the `return_url` you send when creating a session may add a path
ES256 public JWKs	One or two `ES256`/`P-256` public JSON Web Keys (no private `d` value)

Register the origin only: https://app.example.com. The return_url you send when creating a session may add a path, for example https://app.example.com/approval-return. Attesso compares scheme, host, and port, and returns the browser to the exact URL you sent. The origin must match the registered value exactly: http://localhost:43117 and http://127.0.0.1:43117 are different origins. Test keys accept loopback HTTP only with an explicit port. 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 \
  -pkeyopt ec_param_enc:named_curve \
  -out identity.pem

ec_param_enc:named_curve is not optional. Without it, OpenSSL 3.x writes the curve as explicit parameters, and Go’s crypto/x509 (and some other standard libraries) cannot parse the resulting file at all. The key is still valid; it is just unreadable to a large share of stacks. 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. Approval trust is workspace-wide and per environment: one identity issuer and one return origin, with one or two ES256 public keys for rotation. A second registration with different values is refused with 409 APPROVAL_TRUST_ALREADY_REGISTERED. If you run several agent products, give each its own workspace when they need distinct approval brands or return origins; keys rotate in place, but the issuer and origin do not.

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. The passkey is bound to the assertion subject. The first approval for a subject registers a passkey; later approvals by that end user assert the registered credential. Keep subject_reference stable for a person and distinct between people.

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"],
    },
)

Go

Standard library only. ecdsa.SignASN1 would produce DER, so sign the digest and write the 64-byte R || S form yourself; Attesso rejects a DER signature.

package main

import (
	"crypto/ecdsa"
	"crypto/elliptic"
	"crypto/rand"
	"crypto/sha256"
	"crypto/x509"
	"encoding/base64"
	"encoding/json"
	"encoding/pem"
	"fmt"
	"os"
	"time"
)

func b64(b []byte) string { return base64.RawURLEncoding.EncodeToString(b) }

func segment(v any) string {
	encoded, err := json.Marshal(v)
	if err != nil {
		panic(err)
	}
	return b64(encoded)
}

func main() {
	raw, err := os.ReadFile(os.Getenv("IDENTITY_PRIVATE_KEY_PATH"))
	if err != nil {
		panic(err)
	}
	block, _ := pem.Decode(raw)
	key, err := x509.ParsePKCS8PrivateKey(block.Bytes)
	if err != nil {
		panic(err)
	}
	privateKey := key.(*ecdsa.PrivateKey)
	if privateKey.Curve != elliptic.P256() {
		panic("key must be P-256")
	}

	now := time.Now().Unix()
	jti := make([]byte, 16)
	if _, err := rand.Read(jti); err != nil {
		panic(err)
	}

	header := segment(map[string]string{
		"typ": "attesso-identity+jwt",
		"alg": "ES256",
		"kid": os.Getenv("IDENTITY_KEY_ID"),
	})
	payload := segment(map[string]any{
		"iss": os.Getenv("IDENTITY_ISSUER"),
		"sub": mandateSubjectReference,
		"aud": "urn:attesso:approval:test:v1",
		"iat": now,
		"exp": now + 300,
		"jti": b64(jti),
	})

	signingInput := header + "." + payload
	digest := sha256.Sum256([]byte(signingInput))
	r, s, err := ecdsa.Sign(rand.Reader, privateKey, digest[:])
	if err != nil {
		panic(err)
	}
	signature := make([]byte, 64)
	r.FillBytes(signature[:32])
	s.FillBytes(signature[32:])

	fmt.Println(signingInput + "." + b64(signature))
}

Create and handle the session

Send the assertion with a pre-registered return URL and an unpredictable return_state:

POST /v1/mandates/{mandate_id}/approval-sessions
Authorization: Bearer att_test_...
Idempotency-Key: approval_01J...
Content-Type: application/json

{
  "identity_assertion": "<compact JWS>",
  "return_url": "https://app.example.com/approval-return",
  "return_state": "st_9f2c1b7e4a6d"
}

return_state is required: 16 to 256 characters from A-Z a-z 0-9 . _ ~ -. Attesso returns it unchanged in the fragment. A new session invalidates any previous open session for the same Mandate.

{
  "id": "aps_...",
  "mandate_id": "mnd_...",
  "state": "OPEN",
  "approval_url": "https://approve-staging.attesso.com/...",
  "expires_at": "2026-10-18T09:15:00Z",
  "created_at": "2026-10-18T09:10:00Z"
}

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

Bounds

PSP integrations

Reference

Hosted approval

Configure approval trust

Identity assertion contract

TypeScript

Python

Go

Create and handle the session

​Configure approval trust

​Identity assertion contract

​TypeScript

​Python

​Go

​Create and handle the session

Configure approval trust

Identity assertion contract

TypeScript

Python

Go

Create and handle the session