PingOne Platform APIs

Create Credential Verification Session (NATIVE - Push Notification)

   

POST {{apiPath}}/environments/{{envID}}/presentationSessions

Use the POST {{apiPath}}/environments/{{envID}}/presentationSessions to initiate verification of a user credential using the native protocol of the PingOne Credentials service and use a push notification to the user’s digital wallet. Each credential verification session silently times out after 5 minutes.

Prerequisites

Request Model

Refer to Credential Verifications session data model for full property descriptions.

Property Type Required

applicationInstance.id

String

N/A

digitalWalletApplication.id

String

N/A

issuerFilter.environmentIds

String[]

Optional

message

String

Optional

notification

Object

Optional

notification.template

Object

Optional

notification.template.locale

String

Optional

notification.template.variables

Object[]

Required/Optional

notification.template.variant

String

Optional

protocol

String

Optional

requestedCredentials

Object[]

Required

requestedCredentials.keys

String[]

Optional

requestedCredentials.type

String

Required

After receipt of this request, the credential service uses the credential_verification notification template to send a push notification to a digital wallet. The notification.template object can define a variant and locale for the notifications, if needed.

Content of requestedCredentials differs by protocol. The protocol of NATIVE permits multiple credential types per request and uses requestedCredentials.keys to return only those selected data fields for each credential type.

The service searches all environments listed in issuerFilter.environmentIds for the issuer of the presented credential. If the user presents a credential that is not from one of these issuers, the verification fails with status of VERIFICATION_FAILED.

Headers

Authorization      Bearer {{accessToken}}

Content-Type      application/json

Body

raw ( application/json )

{
    "protocol": "NATIVE",
    "message": "Requesting a Verifiable Credential",
    "applicationInstance": {
        "id": "{{applicationInstanceID}}"
    },
    "digitalWalletApplication": {
        "id": "{{digitalWalletApplicationID}}"
    },
    "notification": {
        "template": {
            "locale": "en",
            "variant": "variant_B",
            "variables": {}
        }
    },
    "requestedCredentials": [
        {
            "type": "Driver License",
            "keys": [
                "First Name",
                "Last Name"
            ]
        }
    ]
}

Example Request

  • cURL

  • C#

  • Go

  • HTTP

  • Java

  • jQuery

  • NodeJS

  • Python

  • PHP

  • Ruby

  • Swift

curl --location --globoff '{{apiPath}}/environments/{{envID}}/presentationSessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
    "protocol": "NATIVE",
    "message": "Requesting a Verifiable Credential",
    "applicationInstance": {
        "id": "{{applicationInstanceID}}"
    },
    "digitalWalletApplication": {
        "id": "{{digitalWalletApplicationID}}"
    },
    "notification": {
        "template": {
            "locale": "en",
            "variant": "variant_B",
            "variables": {}
        }
    },
    "requestedCredentials": [
        {
            "type": "Driver License",
            "keys": [
                "First Name",
                "Last Name"
            ]
        }
    ]
}'
var options = new RestClientOptions("{{apiPath}}/environments/{{envID}}/presentationSessions")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("", Method.Post);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Bearer {{accessToken}}");
var body = @"{" + "\n" +
@"    ""protocol"": ""NATIVE""," + "\n" +
@"    ""message"": ""Requesting a Verifiable Credential""," + "\n" +
@"    ""applicationInstance"": {" + "\n" +
@"        ""id"": ""{{applicationInstanceID}}""" + "\n" +
@"    }," + "\n" +
@"    ""digitalWalletApplication"": {" + "\n" +
@"        ""id"": ""{{digitalWalletApplicationID}}""" + "\n" +
@"    }," + "\n" +
@"    ""notification"": {" + "\n" +
@"        ""template"": {" + "\n" +
@"            ""locale"": ""en""," + "\n" +
@"            ""variant"": ""variant_B""," + "\n" +
@"            ""variables"": {}" + "\n" +
@"        }" + "\n" +
@"    }," + "\n" +
@"    ""requestedCredentials"": [" + "\n" +
@"        {" + "\n" +
@"            ""type"": ""Driver License""," + "\n" +
@"            ""keys"": [" + "\n" +
@"                ""First Name""," + "\n" +
@"                ""Last Name""" + "\n" +
@"            ]" + "\n" +
@"        }" + "\n" +
@"    ]" + "\n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "{{apiPath}}/environments/{{envID}}/presentationSessions"
  method := "POST"

  payload := strings.NewReader(`{
    "protocol": "NATIVE",
    "message": "Requesting a Verifiable Credential",
    "applicationInstance": {
        "id": "{{applicationInstanceID}}"
    },
    "digitalWalletApplication": {
        "id": "{{digitalWalletApplicationID}}"
    },
    "notification": {
        "template": {
            "locale": "en",
            "variant": "variant_B",
            "variables": {}
        }
    },
    "requestedCredentials": [
        {
            "type": "Driver License",
            "keys": [
                "First Name",
                "Last Name"
            ]
        }
    ]
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("Authorization", "Bearer {{accessToken}}")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := io.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
POST /environments/{{envID}}/presentationSessions HTTP/1.1
Host: {{apiPath}}
Content-Type: application/json
Authorization: Bearer {{accessToken}}

{
    "protocol": "NATIVE",
    "message": "Requesting a Verifiable Credential",
    "applicationInstance": {
        "id": "{{applicationInstanceID}}"
    },
    "digitalWalletApplication": {
        "id": "{{digitalWalletApplicationID}}"
    },
    "notification": {
        "template": {
            "locale": "en",
            "variant": "variant_B",
            "variables": {}
        }
    },
    "requestedCredentials": [
        {
            "type": "Driver License",
            "keys": [
                "First Name",
                "Last Name"
            ]
        }
    ]
}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"protocol\": \"NATIVE\",\n    \"message\": \"Requesting a Verifiable Credential\",\n    \"applicationInstance\": {\n        \"id\": \"{{applicationInstanceID}}\"\n    },\n    \"digitalWalletApplication\": {\n        \"id\": \"{{digitalWalletApplicationID}}\"\n    },\n    \"notification\": {\n        \"template\": {\n            \"locale\": \"en\",\n            \"variant\": \"variant_B\",\n            \"variables\": {}\n        }\n    },\n    \"requestedCredentials\": [\n        {\n            \"type\": \"Driver License\",\n            \"keys\": [\n                \"First Name\",\n                \"Last Name\"\n            ]\n        }\n    ]\n}");
Request request = new Request.Builder()
  .url("{{apiPath}}/environments/{{envID}}/presentationSessions")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {{accessToken}}")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "{{apiPath}}/environments/{{envID}}/presentationSessions",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{accessToken}}"
  },
  "data": JSON.stringify({
    "protocol": "NATIVE",
    "message": "Requesting a Verifiable Credential",
    "applicationInstance": {
      "id": "{{applicationInstanceID}}"
    },
    "digitalWalletApplication": {
      "id": "{{digitalWalletApplicationID}}"
    },
    "notification": {
      "template": {
        "locale": "en",
        "variant": "variant_B",
        "variables": {}
      }
    },
    "requestedCredentials": [
      {
        "type": "Driver License",
        "keys": [
          "First Name",
          "Last Name"
        ]
      }
    ]
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require('request');
var options = {
  'method': 'POST',
  'url': '{{apiPath}}/environments/{{envID}}/presentationSessions',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{accessToken}}'
  },
  body: JSON.stringify({
    "protocol": "NATIVE",
    "message": "Requesting a Verifiable Credential",
    "applicationInstance": {
      "id": "{{applicationInstanceID}}"
    },
    "digitalWalletApplication": {
      "id": "{{digitalWalletApplicationID}}"
    },
    "notification": {
      "template": {
        "locale": "en",
        "variant": "variant_B",
        "variables": {}
      }
    },
    "requestedCredentials": [
      {
        "type": "Driver License",
        "keys": [
          "First Name",
          "Last Name"
        ]
      }
    ]
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
import requests
import json

url = "{{apiPath}}/environments/{{envID}}/presentationSessions"

payload = json.dumps({
  "protocol": "NATIVE",
  "message": "Requesting a Verifiable Credential",
  "applicationInstance": {
    "id": "{{applicationInstanceID}}"
  },
  "digitalWalletApplication": {
    "id": "{{digitalWalletApplicationID}}"
  },
  "notification": {
    "template": {
      "locale": "en",
      "variant": "variant_B",
      "variables": {}
    }
  },
  "requestedCredentials": [
    {
      "type": "Driver License",
      "keys": [
        "First Name",
        "Last Name"
      ]
    }
  ]
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{accessToken}}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('{{apiPath}}/environments/{{envID}}/presentationSessions');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer {{accessToken}}'
));
$request->setBody('{\n    "protocol": "NATIVE",\n    "message": "Requesting a Verifiable Credential",\n    "applicationInstance": {\n        "id": "{{applicationInstanceID}}"\n    },\n    "digitalWalletApplication": {\n        "id": "{{digitalWalletApplicationID}}"\n    },\n    "notification": {\n        "template": {\n            "locale": "en",\n            "variant": "variant_B",\n            "variables": {}\n        }\n    },\n    "requestedCredentials": [\n        {\n            "type": "Driver License",\n            "keys": [\n                "First Name",\n                "Last Name"\n            ]\n        }\n    ]\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}
require "uri"
require "json"
require "net/http"

url = URI("{{apiPath}}/environments/{{envID}}/presentationSessions")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer {{accessToken}}"
request.body = JSON.dump({
  "protocol": "NATIVE",
  "message": "Requesting a Verifiable Credential",
  "applicationInstance": {
    "id": "{{applicationInstanceID}}"
  },
  "digitalWalletApplication": {
    "id": "{{digitalWalletApplicationID}}"
  },
  "notification": {
    "template": {
      "locale": "en",
      "variant": "variant_B",
      "variables": {}
    }
  },
  "requestedCredentials": [
    {
      "type": "Driver License",
      "keys": [
        "First Name",
        "Last Name"
      ]
    }
  ]
})

response = http.request(request)
puts response.read_body
let parameters = "{\n    \"protocol\": \"NATIVE\",\n    \"message\": \"Requesting a Verifiable Credential\",\n    \"applicationInstance\": {\n        \"id\": \"{{applicationInstanceID}}\"\n    },\n    \"digitalWalletApplication\": {\n        \"id\": \"{{digitalWalletApplicationID}}\"\n    },\n    \"notification\": {\n        \"template\": {\n            \"locale\": \"en\",\n            \"variant\": \"variant_B\",\n            \"variables\": {}\n        }\n    },\n    \"requestedCredentials\": [\n        {\n            \"type\": \"Driver License\",\n            \"keys\": [\n                \"First Name\",\n                \"Last Name\"\n            ]\n        }\n    ]\n}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "{{apiPath}}/environments/{{envID}}/presentationSessions")!,timeoutInterval: Double.infinity)
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
request.addValue("Bearer {{accessToken}}", forHTTPHeaderField: "Authorization")

request.httpMethod = "POST"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
}

task.resume()

Example Response

202 Accepted

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/presentationSessions/365d18f0-ab78-4f02-9791-a6ff27cff02d"
        },
        "qr": {
            "href": "https://api.pingone.com/v1/distributedid/requests/9be6b3ff-eb8d-4615-bd14-7bd3d8ebfdad"
        },
        "appOpenUrl": {
            "href": "https://credentials.customer.com?u=https%3A%2F%2Fapi.pingone.com%2Fv1%2Fdistributedid%2Frequests%2F9be6b3ff-eb8d-4615-bd14-7bd3d8ebfdad"
        }
    },
    "id": "365d18f0-ab78-4f02-9791-a6ff27cff02d",
    "status": "INITIAL",
    "notification": {
        "template": {
            "locale": "en",
            "variant": "variant_B"
        },
        "result": {
            "sent": true,
            "notification": {
                "id": "001004bc-989b-48eb-a911-bdc1301c2765"
            }
        }
    }
}