Skip to main content
There are three ways to verify that a user holds a valid Soverage identity. Each method suits different integration scenarios. For endpoint details and request/response formats, see the API Reference. Users can share a signed URL containing their identity data, protected by an HMAC-SHA256 signature.

​
How it works

  1. The user generates a verification link from their Soverage dashboard
  2. The link contains their DID, personhood score, and completed attestations
  3. An HMAC-SHA256 signature covers all parameters, preventing tampering

​
Verification

Open the link in a browser. The page validates the signature server-side and displays the user’s verified status. If any parameter has been modified, the signature check fails and an error is shown. This method is browser-based. For programmatic or server-side verification, use the OID4VP flow below, which provides cryptographic proofs your application can verify independently using public-key cryptography.
Best for manual or human-readable checks: sharing your verified status in a community, linking from a profile, or quick visual confirmation. Not suited for automated server-side validation.

​
Verifiable Presentations (OID4VP)

For applications that need cryptographically verifiable credentials, Soverage supports the OpenID for Verifiable Presentations (OID4VP) protocol. This allows your application to request specific claims from a user’s W3C Verifiable Credential and verify the cryptographic proof.

​
Integration flow

In the OID4VP protocol, the credential holder’s wallet submits the Verifiable Presentation directly to the verifier via the response_uri provided in the authorization request. There is no intermediary server relaying the presentation.

​
Step by step

1. Create an authorization request Your server calls the Soverage API to create a VP request, specifying the credentials and constraints you require. The API returns a shareUrl that encodes the authorization request, a unique challenge (nonce), and an expiration time. 
POST /api/vp/request
Content-Type: application/json

{
  "requestedCredentials": [
    {
      "type": "PersonhoodCredential",
      "constraints": {
        "minScore": 60
      }
    }
  ]
}
Response: 
{
  "id": "a1b2c3d4e5f6g7h8",
  "challenge": "random-challenge-token",
  "openid4vpUri": "openid4vp://?response_type=vp_token&client_id=...&nonce=...&presentation_definition=...&response_uri=...&response_mode=direct_post",
  "shareUrl": "https://gateway.soverage.com/verify?vp_request=a1b2c3d4e5f6g7h8",
  "expiresAt": "2026-02-19T15:30:00.000Z",
  "status": "pending"
}
2. Display the request Encode openid4vpUri as a QR code for the user to scan with an OID4VP-compatible wallet. The shareUrl is a web fallback that opens the Soverage Gateway in a browser for users without a native wallet. 3. User reviews and authorizes The credential holder opens the link, reviews the requested fields, and authorizes the presentation. Their wallet constructs a Verifiable Presentation containing the requested credentials. 4. Wallet submits the VP to your endpoint Per the OID4VP spec, the wallet POSTs the Verifiable Presentation directly to your response_uri: 
{
  "holder": "did:hedera:testnet:z6Mk...",
  "type": ["VerifiablePresentation"],
  "verifiableCredential": [
    {
      "type": ["VerifiableCredential", "PersonhoodCredential"],
      "credentialSubject": {
        "id": "did:hedera:testnet:z6Mk...",
        "personhoodScore": 85
      }
    }
  ],
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2026-02-19T15:20:00.000Z",
    "proofPurpose": "authentication",
    "challenge": "random-challenge-token",
    "verificationMethod": "did:hedera:testnet:z6Mk...#key-1",
    "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..signature"
  }
}
5. Verify the cryptographic proof The presentation includes an Ed25519 signature in the proof.jws field (detached JWS). Check that:
  • The proof.jws signature is valid against the holder’s DID public key
  • The proof.challenge matches the nonce from your original request
  • The personhood score meets your minimum threshold
  • The credential type is PersonhoodCredential
  • The credential has not expired
See the full API Reference for detailed request/response formats and error codes.
Best for applications that need strong cryptographic guarantees: DeFi protocols, DAO governance, token gates, or any scenario where you need to verify specific claims about a user’s identity. Try the demo to see a working integration with code examples.

​
On-chain token lookup

Each verified user can mint a non-transferable Personhood Token. Your application can query the ledger directly to check if a wallet holds one.

​
Token properties

  • Non-transferable: bound to the original wallet, cannot be sold or sent
  • Unique: maximum supply of 1 per verified user
  • Publicly verifiable: queryable on the ledger
  • Minimal metadata: wallet reference, personhood score, verification flag. No PII.

​
Verification

Query the network to check if a wallet address holds a valid Personhood Token. You can use the network’s SDK or mirror/explorer APIs to look up token balances.
Best for on-chain applications: smart contracts, DAOs, and DeFi protocols that need to gate access based on verified human status without any off-chain API calls.