Authorization Request

The credential presentation flow begins when your application redirects the user to Proof's authorization endpoint. This is a standard OAuth 2.0 authorization request extended with OpenID4VP parameters.

GET https://api.proof.com/verifiable-credentials/v1/presentation/authorize

Flow

Redirect — Your application constructs an authorization request URL and redirects the user's browser to Proof.
Authenticate — Proof authenticates the user against their cloud wallet. If the user has not enrolled, Proof initiates identity verification.
Consent — Proof displays a consent screen showing which claims are being requested and by whom.
Build VP — Upon consent, Proof constructs the VP Token with only the requested disclosures and a Key Binding JWT.
Callback — Proof redirects the user back to your redirect_uri with the vp_token.

Request Parameters

Parameter	Type		Description
`response_type`	String	Required	Must be `vp_token`.
`client_id`	String	Required	Your Proof OAuth Application Client ID.
`redirect_uri`	String	Required	The callback URL where the user is returned. Must match a registered URI.
`scope`	String	Required	Space-separated list of scopes that translate to DCQL queries. See Scopes.
`login_hint`	String	Required	The email address associated with the end-user.
`nonce`	String	Required	Unique cryptographically random string (≥16 chars). Bound into the KB-JWT to prevent replay attacks.
`state`	String	Optional	Opaque value to maintain state between request and callback. Returned unmodified.
`transaction_data`	String	Optional	Space-separated base64url-encoded JSON objects containing transaction data to bind. See Transaction Data.

Example Request

POST /verifiable-credentials/v1/presentation/authorize?
  response_type=vp_token
  &client_id=your_client_id
  &redirect_uri=https://app.example.com/callback
  &scope=urn:proof:params:scope:verifiable-credentials:basic
  &[email protected]
  &nonce=n-0S6_WzA2Mj_6a8bRs2TU
  &state=af0ifjsldkj

ℹ️
The URL above is shown with line breaks for readability. In production, this must be a single URL with no whitespace.

Scopes

Each scope maps to a predefined set of Selective Disclosures that will be included in the Verifiable Presentation. Pass one or more scopes in the scope parameter to control which claims are requested from the user's credential.

Scope	Selective Disclosures
`urn:proof:params:scope:verifiable-credentials:basic`	`given_name`, `family_name`, `age_equal_or_over.18`

Transaction Data Binding

Each transaction_data value is a base64url-encoded JSON object with the following properties:

Property	Type		Description
`type`	String	Required	One of the supported transaction data types listed below.
`credential_ids`	String[]	Required	Array of credential query IDs this transaction data applies to.
`payload`	Object	Required	Type-specific data to bind into the presentation. Varies by `type`.

Session Data

urn:proof:params:vc:transaction-data:session-data

Binds session context to the presentation.

`payload`

Property	Type		Description
`ip_address`	String	Required	IP address of the end-user.
`device_id`	String	Optional	Device identifier of the end-user.

Itemized Payment

urn:proof:params:vc:transaction-data:payment-itemized:v1

Binds an itemized payment summary to the presentation.

`payload`

Property	Type		Description
`title`	String	Optional	Title of the payment.
`description`	String	Optional	Description of the payment.
`currency`	String	Required	Currency code (e.g., `USD`).
`items`	Object[]	Required	List of line items in the payment.

Each object in items:

Property	Type		Description
`quantity`	Integer	Required	Quantity of the item.
`unit_cost`	Float	Required	Cost per unit of the item.
`label`	String	Required	Label describing the item.

Wire Instructions

urn:proof:params:vc:transaction-data:wire-instructions:v1

Binds wire transfer instructions to the presentation.

`payload`

Property	Type		Description
`recipient`	Object	Required	The recipient of the wire transfer.
`source`	Object	Required	The funding source for the wire transfer.
`amount`	Float	Required	Transfer amount.
`currency`	String	Required	Currency code (e.g., `USD`).
`memo`	String	Optional	Memo or reference note for the transfer.

recipient object:

Property	Type		Description
`individual_name`	String	Optional	Name of the recipient individual.
`institution_name`	String	Required	Name of the recipient institution.
`routing_number`	String	Required	Routing number of the recipient account.
`account_number`	String	Required	Account number of the recipient.
`website`	String	Optional	Website of the recipient.

source object:

Property	Type		Description
`individual_name`	String	Required	Name of the source individual.
`institution_name`	String	Optional	Name of the source institution.
`account_number`	String	Required	Account number of the source.
`routing_number`	String	Required	Routing number of the source account.

Payment Mandate

urn:proof:params:vc:transaction-data:payment-mandate:v1

Binds a payment mandate authorization to the presentation.

`payload`

Property	Type		Description
`payment_instrument`	Object	Required	The payment instrument used for the mandate.
`payee`	Object	Required	The payee receiving the payment.
`prompt_summary`	String	Required	Summary text displayed to the user for consent.
`amount`	Float	Required	Payment amount.
`currency`	String	Required	Currency code (e.g., `USD`).

payment_instrument object:

Property	Type		Description
`type`	String	Required	Type of payment instrument.
`id`	String	Required	Identifier of the payment instrument.
`instruction`	String	Optional	Instruction associated with the instrument.

payee object:

Property	Type		Description
`id`	String	Optional	Identifier of the payee.
`name`	String	Required	Name of the payee.
`website`	String	Optional	Website of the payee.

Authorization Response

After the user authenticates and consents, Proof redirects the browser back to your redirect_uri. The response parameters are appended as a URI fragment.

REDIRECT https://app.example.com/callback#vp_token=...&state=...

Response Parameters

Parameter	Type		Description
`vp_token`	String	Always	The SD-JWT VC string
`state`	String	Conditional	Returned if a `state` value was provided in the request.