How the API works

How it works, not an exhaustive list of routes: enough to know in a few minutes whether Todis fits your needs.

In three steps

1

You authenticate with the token received by email at signup.

2

You send a proof to Todis, either directly or through a guided flow with your user's wallet.

3

You get a clear result: verified or not, with only the information you asked for.

Authenticating

Every call uses the token received by email at signup, passed in the Authorization: Bearer <token> header. A missing, invalid, or expired token always returns a 401.

Two ways to integrate

Depending on whether you already have your user's proof in hand, or would rather let Todis handle the exchange with their wallet.

Direct verification

You've already received your user's proof (SD-JWT VC or mdoc) through some other channel. A single HTTP call gets it verified: 

curl -X POST https://verify.todis.eu/verify/sd-jwt-vc \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "presentation": "<proof received from the wallet>",
    "country_code": "FR"
  }'

country_code lets Todis automatically resolve the issuer via the EU's official registry. You can also supply its public key directly with issuer_public_key_pem if you already know it.

Full flow (OpenID4VP)

You ask Todis to create a verification session. Your user scans a QR code or opens their wallet, which sends its response directly to Todis. You then retrieve the result via the session identifier.

This is the method that simplifies your integration the most: your application never has to receive or parse the wallet's raw response, it gets a result already verified by Todis!

Who decides what gets shared

In a European wallet, each piece of information (age, a degree, a status) is separately protected by its own cryptographic proof. The wallet only attaches to its response the proofs for the information the user agreed to share: everything else stays invisible, not just hidden. Todis technically cannot see it, authorized or not.

With the full flow, you decide what information to ask for, through the claims field of your request (for example ["age_over_18"]). Todis passes that request to the wallet, which shows the user a consent screen listing exactly the requested information before they accept. With direct verification, that step has already happened before the proof reaches Todis: you send us an already-built proof, we verify it and return its content as is, without adding or removing anything.

The response

In both cases, the response is simple: verified or not, with only the information actually disclosed (see above): 

{
  "verified": true,
  "claims": { "age_over_18": true }
}

Need the full detail?

Response codes and error cases: see the technical reference. Exact request/response schema: todis.eu/en/docs (Swagger). Still have a question? contact@todis.eu.