Proof supports returning OpenID Connect style responses from transactions created via the API that can allow customers to integrate Proof seamlessly into workflows and authenticate users' responses while utilizing standard libraries and tools used for other authentication and authorization workflows.

Setup

In order to create OpenID Connect style transactions, you'll need to have an OAuth client application created for your organization. Details about Proof's OAuth configuration are available here. In addition to the settings detailed on that page, any redirect URIs that will be used to receive authenticated responses from Proof will also need to be configured on your OAuth application.

Creating OpenID Connect Transactions

Currently, receiving OpenID Connect responses is only possible through transactions created via the Create OpenId Connect Transaction API.

Response Format

After any OpenID Connect transaction completes, users will be redirected back to your provided redirect_uri parameter passed in the transaction creation request along with an OAuth authorization code parameter and, if passed in the creation request, the provided OAuth scope parameter.

Example redirect response:

HTTP 302 Found
Location: https://partner.com/verification/callback/?code=MelsetXiSMElWknW8n94JpAiHCF9vfK60a2nrR-xJ5&state=<state-value>

OAuth Code API

Request

The returned OAuth authorization code can be exchanged with a POST call to https://api.proof.com/oauth/v2/token as per the OAuth 2.0 RFC.

POST https://api.proof.com/oauth/v2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ

grant_type=authorization_code&
code=MelsetXiSMElWknW8n94JpAiHCF9vfK60a2nrR-xJ5Q&
redirect_uri=https://partner.com/verification/callback

Parameter	Type	Description
`grant_type`	String	Must be `authorization_code`
`code`	String	The provided OAuth authorization code
`redirect_uri`	String	The `redirect_uri` parameter that was provided at transaction creation time
`client_id`	String	(Optional) The client ID for the OAuth client application provided at transaction creation time
`client_secret`	String	(Optional) A valid client secret for the OAuth client application being used

Note: client_id and client_secret are optional parameters; client credentials can be provided either as parameters in the request body, or (preferred) in the Authorization: Basic header (as indicated in Proof's client_credentials guide).

Response

{
   "access_token": "RMiAr938z97bLO_Zn_at3OQFY0hxoBCxaWwk8fJ9syE",
   "token_type": "Bearer",
   "expires_in": 7200,
   "id_token": "eyJ0eXAiOiJKV1QiLCJraWQiOiI4ZmY0ZDA0Mi1mM2YwLTQ3OGQtOTY0NC03OWY0MmE2ODg4OWQiLCJhbGciOiJSUzI1NiJ9.eyJleHAiOjE3ODU1Mjk1MjEsImlhdCI6MTc4NTUyOTIyMSwiaXNzIjoiaHR0cHM6Ly9hcGkuc3RhZ2luZy5wcm9vZi5jb20iLCJhdWQiOiJjYTZuejZqOW4iLCJhenAiOiJjYTZuejZqOW4iLCJzdWIiOiJvYzdnM3BxanAiLCJzdWJfdHlwZSI6InJlY2lwaWVudCIsImV4dGVybmFsX2lkIjoiZXhhbXBsZS1leHRlcm5hbC1pZGVudGlmaWVyIiwidmVyaWZpZWRfY2xhaW1zIjp7InZlcmlmaWNhdGlvbiI6eyJ0cnVzdF9mcmFtZXdvcmsiOiJ1cm46cHJvb2Y6cGFyYW1zOnRydXN0LWZyYW1ld29yazprbm93bGVkZ2UtYmFzZWQiLCJhc3N1cmFuY2VfbGV2ZWwiOiJGQUlMRUQifSwiY2xhaW1zIjp7ImdpdmVuX25hbWUiOm51bGwsImZhbWlseV9uYW1lIjpudWxsfX19.V-5mgX7hkVnc0VBmLaO9TVaYL_8QQvjbYFWuGO5X6vv39pSO_rIJ6fRoPb_8lqmuAVyx1wEKnGROryqn1xVwezxbPSTRTYiHCC20Wl0bHHpL0NqLV26l4mqFBCpH84qf4aJDQAjGnjb7qo019uXIENMtaD_oQZPUZwhybNmiQuTTl15Am-nF2HhTxNaFlo-AdPJOlFNiyC3gjNuZ_cnbXyjOa2ZNVsg5QzD8G3741KtIKTGFHExdxkPd82u_j30XZ1kFyl1hB3h4kjRH8jITNLoC56kd560kDvbefTePspwUOGXKtuAUiD-x1uQuyPIQsK4ZFn9WHSXjxa_Ul5gVsobHragUyW0imUjzvfHrFeekKAjI3YVwOTEfgRCNK5QlsqnOK1Ht6t9uf_QVb8ZFtsqPuuqbtQmM342fi0dk22nqJdm-e79S3z34qJYLNvQuHRo5J_Hk8YWSV2puzd0XJ9i3dZsRdpp8HsgauCep0KMLzv77Ct7JJ3bA1ls_khybdBEbY18J7vohktkIEOt4Kg1LjEFeP6NShs5pqscP0cXwfh13Pd4qDnxELy-0ELmHOQvYAo1hpZsEkkUqUmw1sEChyQd2_YT8-j0ZlM0rUna3fjv5Z2vpBjheAB85D_gMNdmuyj8ASMriKbuZiXabE6IHhUqzqAOWzYXJudI_n9I"
}

Parameter	Type	Description
`access_token`	String	The requested access token; can be introspected at the Token Introspection endpoint (below)
`token_type`	String	Will always be `Bearer`
`expires_in`	Integer	The lifetime of the `access_token` in seconds
`id_token`	String	(Optional) If `openid` was passed in the `scope` parameter at transaction creation time, an OpenID Connect ID token containing the information about the user attempting verification

Error Responses

The API will return HTTP 401 Unauthorized if the client credentials are incorrect, the authorization code is expired or has already been exchanged, or the code was not issued to the client whose credentials are provided.

Token Contents

Access Token Introspection

The returned access_token can be introspected at the token info endpoint, detailed here. The access_token is passed in the Authorization: Bearer header of a GET request to https://api.proof.com/oauth/v2/token/info.

GET https://api.proof.com/oauth/v2/token/info
Authorization: Bearer RMiAr938z97bLO_Zn_at3OQFY0hxoBCxaWwk8fJ9syE

The response will include information about the verification session, and if the user succeeded, the requested verified information about that user.

{
   "sub": "ocka38gx9",
   "sub_type": "recipient",
   "external_id": "example-external-identifier",
   "verification": {
       "trust_framework": "urn:proof:params:trust-framework:credential-analysis",
       "assurance_level": "VERIFIED",
       "time": "2026-07-31T20:27:33Z"
   },
   "claims": {
       "given_name": "Sally",
       "family_name": "Signer",
       "birthdate": "1989-12-13"
   }
}

If the user failed verification, the assurance_level provided will be FAILED, there will be no time returned for the verification, and the claims will have JSON null values.

{
   "sub": "oc7g3pqjp",
   "sub_type": "recipient",
   "external_id": "example-external-identifier",
   "verification": {
       "trust_framework": "urn:proof:params:trust-framework:credential-analysis",
       "assurance_level": "FAILED"
   },
   "claims": {
       "given_name": null,
       "family_name": null
   }
}

ID Token

If the scope openid was requested at transaction creation time, an OpenID Connect ID token will also be returned in the id_token parameter of the token response. The ID token will be a JWT signed in the compact JWS format. The key used to sign the JWT is identified by the kid (key ID) parameter in the JWS header; the keys that can be used to sign ID tokens are published at https://api.proof.com/openid-connect/jwks (the JWKs endpoint is also published at https://api.proof.com/.well-known/openid-configuration, the standard OpenID Connect discovery endpoint).

{
  "exp": 1785529970,
  "iat": 1785529670,
  "iss": "https://api.proof.com",
  "azp": "ca6nz6j9n",
  "external_id": "example-external-identifier",
  "verified_claims": {
    "verification": {
      "trust_framework": "urn:proof:params:trust-framework:credential-analysis",
      "assurance_level": "VERIFIED",
      "time": "2026-07-31T20:27:33Z"
    },
    "claims": {
      "given_name": "Sally",
      "family_name": "Signer",
      "birthdate": "1989-12-13"
    }
  }
}

If the user failed verification, the assurance_level provided will be FAILED, there will be no time returned for the verification, and any claims returned will have JSON null values.

{
  "exp": 1785529970,
  "iat": 1785529670,
  "iss": "https://api.proof.com",
  "azp": "ca6nz6j9n",
  "external_id": "example-external-identifier",
  "verified_claims": {
    "verification": {
      "trust_framework": "urn:proof:params:trust-framework:credential-analysis",
      "assurance_level": "FAILED"
    },
    "claims": {
      "given_name": null,
      "family_name": null
    }
  }
}