Skip to main content
GET
/
api
/
v1
/
startsiop
Start SIOP Flow
curl --request GET \
  --url https://api.example.com/api/v1/startsiop
{
  "Content-Type": "<string>",
  "body": "<string>",
  "summary": "<string>",
  "details": "<string>",
  "scope": "<string>",
  "response_type": "<string>",
  "response_mode": "<string>",
  "client_id": "<string>",
  "redirect_uri": "<string>",
  "state": "<string>",
  "nonce": "<string>"
}

​
Overview

The Start SIOP endpoint initiates the SIOP (Self-Issued OpenID Provider) flow and returns an OpenID connection string that can be encoded in a QR code or sent to a wallet application. This endpoint is typically used for cross-device authentication flows.
This endpoint is part of the API tag and can be reused by other applications to integrate credential verification into their authentication flows.

​
Endpoint

GET /api/v1/startsiop

​
Query Parameters

​
state
string
required
Session state identifier used to maintain state between the request and callback. This value must be unique for each authentication session.Example: 274e7465-cc9d-4cad-b75f-190db927e56a
​
client_callback
string
required
Endpoint of the client application to receive the JWT token after successful authentication.Format: URLExample: https://my-portal.com/auth_callback
​
client_id
string
The identifier of the client/service that intends to start the authentication flow. Used to retrieve the scope and trust services for verification.Example: packet-delivery-portal

​
Response

​
200 - Success

Returns the OpenID connection string that can be used to initiate the authentication flow. This string is typically encoded in a QR code for cross-device flows.
​
Content-Type
string
text/plain
​
body
string
The OpenID connection string in the format:
openid://?scope={scope}&response_type=vp_token&response_mode=post&client_id={did}&redirect_uri={uri}&state={state}&nonce={nonce}
Example:
openid://?scope=dsba.credentials.presentation.PacketDeliveryService&response_type=vp_token&response_mode=post&client_id=did:key:z6MktZy7CErCqdLvknH6g9YNVpWupuBNBNovsBrj4DFGn4R1&redirect_uri=http://localhost:3000/verifier/api/v1/authenticationresponse&state=&nonce=BfEte4DFdlmdO7a_fBiXTw

​
400 - Bad Request

Returned when required parameters are missing.
​
summary
string
Error summary message.Example: no_state_provided
​
details
string
Detailed error description.Example: Authentication requires a state provided as query parameter.

​
500 - Internal Server Error

Returned when the SIOP flow cannot be initiated due to server-side issues.
​
summary
string
Error summary describing the failure.
​
details
string
Detailed error information.Example: Was not able to generate the connection string.

​
Examples

curl -X GET "https://verifier.example.com/api/v1/startsiop?state=274e7465-cc9d-4cad-b75f-190db927e56a&client_callback=https://my-portal.com/auth_callback&client_id=packet-delivery-portal"

​
Common Errors

Required Parameters: Both state and client_callback are mandatory. Requests missing either parameter will be rejected with a 400 error.
Error CodeSummaryDetails
400no_state_providedAuthentication requires a state provided as query parameter.
400NoCallbackProvidedA callback address has to be provided as query-parameter.
500Internal ErrorWas not able to generate the connection string.

​
Connection String Components

The returned connection string contains the following components:
​
scope
string
The scope of credentials being requested. Derived from the client configuration.Example: dsba.credentials.presentation.PacketDeliveryService
​
response_type
string
Always set to vp_token for verifiable presentation token.
​
response_mode
string
Always set to post indicating the response will be POSTed to the redirect URI.
​
client_id
string
The DID (Decentralized Identifier) of the verifier.Example: did:key:z6MktZy7CErCqdLvknH6g9YNVpWupuBNBNovsBrj4DFGn4R1
​
redirect_uri
string
The URI where the wallet should POST the authentication response.Example: https://verifier.example.com/api/v1/authentication_response
​
state
string
The state value provided in the request, used to correlate the response.
​
nonce
string
A unique nonce generated by the verifier to prevent replay attacks.Example: BfEte4DFdlmdO7a_fBiXTw

​
Flow Diagram

​
Implementation Notes

​
Protocol Detection

The endpoint automatically detects the request protocol:
  • HTTPS: Used when TLS is present (recommended for production)
  • HTTP: Used when TLS is absent (development only)

​
Default Request Mode

If not specified in the client configuration, the default request mode is byReference, which means the authorization request details are passed by reference rather than by value.

​
Client Configuration

When a client_id is provided:
  • The verifier retrieves the configured scope for that client
  • Trust services and verification policies specific to the client are applied
  • If no client_id is provided, default verification policies are used

​
Nonce Generation

The verifier automatically generates a unique nonce for each session to:
  • Associate the client session with the authentication response
  • Mitigate replay attacks
  • Ensure freshness of the authentication

​
Security Considerations

State Parameter: Always use a cryptographically random, unique value for the state parameter. Reusing state values can lead to session fixation attacks.
  • HTTPS Only: In production, always use HTTPS to prevent interception of credentials
  • State Validation: The client must validate that the state in the callback matches the original request
  • Nonce Validation: The verifier validates the nonce in the authentication response
  • Callback URL: Ensure the client_callback URL is on an allowlist to prevent token theft

​
Use Cases

​
QR Code Authentication

  1. Client application calls /api/v1/startsiop
  2. Receives OpenID connection string
  3. Generates QR code from the connection string
  4. User scans QR code with wallet app
  5. Wallet sends verifiable presentation to verifier
  6. Verifier sends JWT to client callback
  1. Mobile app calls /api/v1/startsiop
  2. Receives OpenID connection string
  3. Converts to a mobile deeplink
  4. Opens wallet app on the same device
  5. Wallet completes authentication flow

​
API Integration

Other services can use this endpoint to integrate credential verification: 
// Service A wants to verify a user's credentials
const connectionString = await startSiopFlow({
  state: generateUniqueState(),
  callback: 'https://service-a.com/auth/callback',
  clientId: 'service-a'
});

// Use connectionString for QR code or deeplink

Build docs developers (and LLMs) love

Get started for freeTalk to us