Prove Endpoint API Reference

The /prove endpoint is based on the OpenID for Verifiable Presentation direct_post response mode. See Integration Guide for details.

POST /prove

Starts an identity verification flow.

Authentication

Bearer token (see Authentication).

Request

Request

cURL

curl -X POST https://api.test.lithosid.com/prove \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"issuer": "xx-sandbox", "revealed": ["family_name"], "state": "unique-state-id"}'

Go

client, err := lithosid.NewClient(opts)
if err != nil {
	return "", err
}

result, err := client.Prove(ctx, lithosid.ProveParams{
	Issuer:   "xx-sandbox",
	Revealed: []lithosid.AttributeID{lithosid.AttrFamilyName},
	State:    state,
})
if err != nil {
	return "", err
}

return result.RedirectURL, nil

Typescript

const client = new Client(clientOptions);

const result = await client.prove({
  issuer: IssuerSandbox,
  revealed: [AttrFamilyName],
  state,
});

if (!result.ok) {
  throw new Error(`${result.error.error}: ${result.error.errorDescription}`);
}

return result.redirectUrl;

Response

200

{
  "success": true,
  "redirect_url": "https://issuer.example.com"
}

400

{
  "success": false,
  "error": {
    "error": "error_missing_state",
    "error_description": "missing state"
  }
}

Request Body

issuer string

Required.

Government Identity App (identity wallet) identifier.

revealed string[]

Required.

Array of PID attribute IDs (see PID Attribute IDs).

Minimum length: 1.

state string

Required.

A unique value generated by your application. Lithos ID returns this value unchanged in both success and error callbacks.

same_device boolean

Optional.

Default: false

Whether the Government Identity App (identity wallet) should be opened on the same device. Set this to true if the user is using a mobile device.

Callback

After the user completes identity verification, Lithos ID sends a POST request to the Redirect URL configured in the Customer Portal.

Success Callback

Content-Type: application/x-www-form-urlencoded

Parameter	Type	Description
presentation	string	Cryptographic proof of the user's Personal Identification Data (PID).
state	string	The state value supplied in the /prove request.

Example:

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

presentation=...
state=unique-state-id

Error Callback

If identity verification cannot be completed, Lithos ID sends an error callback instead.

Content-Type: application/x-www-form-urlencoded

Parameter	Type	Description
error	string	Error code.
error_description	string	Human-readable description of the error.
state	string	The state value supplied in the /prove request.

Example:

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

error=error_invalid_request
error_description=...
state=unique-state-id

Response

Your endpoint must respond with:

• HTTP status code 200 OK
• Content-Type: application/json

Response body:

{
  "redirect_uri": "https://your-application.example.com/verification-complete"
}

After receiving a successful response, Lithos ID redirects the user's browser to redirect_uri.

Our SDKs expose helpers to simplify parsing the callback and responding to it:

Go

resp, err := lithosid.BuildRedirectResponse(redirectURI)
if err != nil {
	return lithosid.RedirectResponse{}, err
}

callback, err := lithosid.ParseProofCallback(rawBody)
if err != nil {
	return resp, err
}
if callback.IsError() {
	return resp, fmt.Errorf("%s: %s", callback.Error, callback.ErrorDescription)
}

verified, err := lithosid.VerifyPresentation(ctx, callback.Presentation, storedValues, opts...)
if err != nil {
	return resp, err
}
if !verified.Valid {
	return resp, fmt.Errorf("proof verification failed: %s", verified.Reason)
}

return resp, nil

Typescript

const response = buildRedirectResponse(redirectUri);

try {
  const callback = parseProofCallback(rawBody);

  if (callback.type === "error") {
    return {
      response,
      error: new Error(`${callback.error}: ${callback.errorDescription}`),
    };
  }

  const verification = await verifyPresentation(
    callback.presentation,
    storedValues,
    options,
  );
  if (!verification.valid) {
    return {
      response,
      error: new Error(`proof verification failed: ${verification.reason}`),
    };
  }

  return { response };
} catch (err) {
  return {
    response,
    error: err instanceof Error ? err : new Error(String(err)),
  };
}

Supported Issuers

de-ausweis — German Ausweis eID system.

xx-sandbox — Available only in the test environment. The Sandbox Issuer always returns the same Personal Identification Data (PID) and is intended for integration testing. See Testing for more details.

PID Attribute IDs

Attributes represent pieces of Personal Identification Data (PID), such as a family name or date of birth. Lithos ID uses the attribute IDs defined by the EUDIW Annex 3.01 PID Rulebook.

ID	Description
family_name	Current last name(s) or surname(s)
given_name	Current first name(s), including middle name(s)
birth_date	Birth date in DD-MM-YYYY format
nationality	Nationalities as ISO 3166-1 alpha-2 country codes

Errors

If an error occurs, Lithos ID always returns error code (error) and error description (error_description).

HTTP Status Code	Error Code	Example Error Description	Possible cause
400	error_invalid_body	"request body is not a valid JSON"	Request body is invalid
400	error_missing_parameter	"state is required"	A required field is missing in the request body
400	error_invalid_attribute	"invalid attribute ID: example_id"	Unknown PID Attribute ID
400	error_wrong_issuer	"invalid issuer ID"	The issuer field has an invalid value
401	error_api_key	"API key missing"	API key is missing or invalid
401	error_account	"account suspended"	Your account is not set up to use the API or it has been suspended
500	error_internal	"cannot start verification job"	An internal error has occurred