PingOne Platform APIs

Create Credential Verification Session (NATIVE)

   

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. 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

protocol

String

Optional

message

String

Optional

requestedCredentials

Object[]

Required

requestedCredentials.keys

String[]

Optional

requestedCredentials.type

String

Required

issuerFilter.environmentIds

String[]

Optional

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 )

{
    "message": "Some custom message for the user.",
    "protocol": "NATIVE",
    "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 '{
    "message": "Some custom message for the user.",
    "protocol": "NATIVE",
    "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" +
@"    ""message"": ""Some custom message for the user.""," + "\n" +
@"    ""protocol"": ""NATIVE""," + "\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(`{
    "message": "Some custom message for the user.",
    "protocol": "NATIVE",
    "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}}

{
    "message": "Some custom message for the user.",
    "protocol": "NATIVE",
    "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    \"message\": \"Some custom message for the user.\",\n    \"protocol\": \"NATIVE\",\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({
    "message": "Some custom message for the user.",
    "protocol": "NATIVE",
    "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({
    "message": "Some custom message for the user.",
    "protocol": "NATIVE",
    "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({
  "message": "Some custom message for the user.",
  "protocol": "NATIVE",
  "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    "message": "Some custom message for the user.",\n    "protocol": "NATIVE",\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({
  "message": "Some custom message for the user.",
  "protocol": "NATIVE",
  "requestedCredentials": [
    {
      "type": "Driver License",
      "keys": [
        "First Name",
        "Last Name"
      ]
    }
  ]
})

response = http.request(request)
puts response.read_body
let parameters = "{\n    \"message\": \"Some custom message for the user.\",\n    \"protocol\": \"NATIVE\",\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/16bab70c-32c1-41ca-9c84-d062aedd095f"
        },
        "qr": {
            "href": "https://api.pingone.com/v1/distributedid/requests/e4974bd1-0094-4586-8e43-28c4409d4bd7"
        },
        "appOpenUrl": {
            "href": "https://shocard.pingone.com/appopen?u=https%3A%2F%2Fapi.pingone.com%2Fv1%2Fdistributedid%2Frequests%2Fe4974bd1-0094-4586-8e43-28c4409d4bd7"
        }
    },
    "id": "16bab70c-32c1-41ca-9c84-d062aedd095f",
    "status": "INITIAL"
}