Lithos ID Documentation

Appearance

Integration Guide ​

The prove endpoint uses a chain of redirects, similar to the flow defined by the OpenID for Verifiable Presentation direct_post response mode.

PlantUML Diagram

The browser is redirected between your application and the Government Identity App (identity wallet), while all communication with the Lithos ID API and the proof callback occurs server-to-server.

Initial Request ​

To start the identity verification process, send a request to the /prove endpoint. The endpoint responds with a URL to which you should redirect the user. See the Prove endpoint API reference for details.

Receiving the Proof ​

After the user has verified their identity, Lithos ID sends a POST request to your Redirect URL.

http
POST /your-return-url
Content-Type: application/x-www-form-urlencoded

  presentation=...
  state=...

If an error occurs, the request contains error details instead.

http
POST /your-return-url
Content-Type: application/x-www-form-urlencoded

  error=error_invalid_request
  error_description=...
  state=...

Your endpoint must respond with HTTP status code 200 OK and a JSON object in the response body.

http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "redirect_uri": "https://where-to-redirect-the-user.yourservice.example.com"
}

Lithos ID then redirects the user to the URL specified by redirect_uri.