Sovera

Quickstart

This guide gets you from zero to a scored liveness result in three steps: get an API key, send a base64 selfie to the liveness endpoint, and read the response. Every example uses the interim base URL https://verify.lioncapventures.com.

Use a test key (svk_test_...) while you build. A key is shown once at creation, then only its SHA-256 hash is stored, so copy it somewhere safe. See Authentication for scopes.

Get an API key

API keys are issued per organization. Contact the Sovera team to provision your organization and issue a key. A test key looks like svk_test_... and a live key looks like svk_live_.... Send it on every request as a bearer token:

Authorization header

Authorization: Bearer svk_test_your_key_here

Run a liveness check

The liveness endpoint takes a single base64-encoded image and tells you whether the face is real and present. It needs the verify:liveness scope.

POST
/v1/verify/liveness
# Encode a selfie to base64 (macOS/Linux)
IMAGE_B64=$(base64 -i selfie.jpg | tr -d '\n')

curl -X POST https://verify.lioncapventures.com/v1/verify/liveness \
  -H "Authorization: Bearer svk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"image\":\"$IMAGE_B64\"}"

Read the response

A successful call returns whether the subject is live, a score, the threshold the score was compared against, and how long detection took.

Response

{
  "isLive": true,
  "score": 0.982,
  "threshold": 0.5,
  "latencyMs": 214,
  "detail": "passive_pad"
}

Interpret it like this:

  • Name
    isLive
    Type
    boolean
    Description

    Sovera's own accept or reject decision for this frame, using the provisional threshold.

  • Name
    score
    Type
    number
    Description

    Confidence from 0 to 1 that the face is real and present. Higher is more confident.

  • Name
    threshold
    Type
    number
    Description

    The score cut-off isLive was derived from. Provisional until in-house ROC calibration.

  • Name
    latencyMs
    Type
    integer
    Description

    Server-side detection time in milliseconds.

Thresholds are provisional. Rather than trusting isLive alone, keep the raw score and set your own accept and reject bands per use case, then tighten them once calibration is published.

Run a hosted verification

For a full end-to-end verification (consent, liveness, document, and a decision), create a session and open the returned link on the subject's phone. There is no capture UI to build.

POST
/v1/sessions
curl -X POST https://verify.lioncapventures.com/v1/sessions \
  -H "Authorization: Bearer $SOVERA_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"flow": ["liveness", "document"]}'

The response carries a hostedUrl. Open it on a phone to run the flow, then read the decision by polling the session or by listening for the signed session.completed webhook.

Response

{
  "sessionId": "1f2e...",
  "status": "created",
  "hostedUrl": "https://id.lioncapventures.com/s/1f2e...?t=svct_...",
  "clientToken": "svct_..."
}

Use a svk_test_ key while integrating. Every new organization starts with free test credits, and live keys require a verified email.

What's next?

Was this page helpful?