PingOne Platform APIs

Read Flow

GET {{authPath}}/{{envID}}/flows/{{flowID}}

The GET /{{envID}}/flows/{{flowID}} operation retrieves information about a flow specified by the flow ID in the request URL.

The status property in the response specifies the next action in the authentication flow.

For a status value of USERNAME_PASSWORD_REQUIRED, the response includes the following links to initiate the next operation in the flow, depending on the sign-on policy:

  • usernamePassword.check

An action to authenticate with a username and password.

  • user.register

    An action to register a new user.

  • password.forgot

    An action to recover a user’s forgotten password.

  • authenticate

    An action to sign on using an external authentication provider.

Log in with external authentication

PingOne supports login integration between external identity providers (such as Facebook) and PingOne authentication flows. For example, if Facebook is specified as an external identity provider, users have the ability to sign on to their PingOne account using their Facebook credentials and Facebook’s account sign-on flow.

When external authentication is enabled, the flow initialization response includes the socialProviders embedded resource, which provides the following information about each external identity provider that can be used by the user to sign on:

"socialProviders" : [ {
  "id" : "179a9005-6f26-4294-9388-fcb0e9323353",
  "name" : "Facebook",
  "type" : "FACEBOOK",
  "_links" : {
    "authenticate" : {
      "href" : "https://auth.pingone.com/5caa81af-ec05-41ff-a709-c7378007a99c/rp/authenticate?providerId=179a9005-6f26-4294-9388-fcb0e9323353&flowId=ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6"
    }
  }
} ]

The authenticate link can be used to redirect the browser to initiate authentication with the associated external identity provider.

For a flow status value of EXTERNAL_AUTHENTICATION_REQUIRED, users must authenticate with an external identity provider to continue the authentication workflow.

Login hint

The login_hint property in an authorize request specifies a login identifier to pre-fill the Username field of the sign-on screen. In the flow response, if the login_hint value is a username, the value is returned in the identifier attribute of the flow response. If the login_hint is a UUID, and the look-up finds a user, the username value is returned in the identifier attribute. If a user is not found, the UUID is returned in the identifier attribute.

    "_embedded": {
        "identifier": "lindajones"
    }

Example Request

  • cURL

  • C#

  • Go

  • HTTP

  • Java

  • jQuery

  • NodeJS

  • Python

  • PHP

  • Ruby

  • Swift

curl --location --globoff '{{authPath}}/{{envID}}/flows/{{flowID}}'
var options = new RestClientOptions("{{authPath}}/{{envID}}/flows/{{flowID}}")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("", Method.Get);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
package main

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

func main() {

  url := "{{authPath}}/{{envID}}/flows/{{flowID}}"
  method := "GET"

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

  if err != nil {
    fmt.Println(err)
    return
  }
  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))
}
GET /{{envID}}/flows/{{flowID}} HTTP/1.1
Host: {{authPath}}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("{{authPath}}/{{envID}}/flows/{{flowID}}")
  .method("GET", body)
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "{{authPath}}/{{envID}}/flows/{{flowID}}",
  "method": "GET",
  "timeout": 0,
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require('request');
var options = {
  'method': 'GET',
  'url': '{{authPath}}/{{envID}}/flows/{{flowID}}',
  'headers': {
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
import requests

url = "{{authPath}}/{{envID}}/flows/{{flowID}}"

payload = {}
headers = {

}

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

print(response.text)
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('{{authPath}}/{{envID}}/flows/{{flowID}}');
$request->setMethod(HTTP_Request2::METHOD_GET);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(

));
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 "net/http"

url = URI("{{authPath}}/{{envID}}/flows/{{flowID}}")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var request = URLRequest(url: URL(string: "{{authPath}}/{{envID}}/flows/{{flowID}}")!,timeoutInterval: Double.infinity)
request.httpMethod = "GET"

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

200 OK

{
  "_links" : {
    "self" : {
      "href" : "https://auth.pingone.com/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/flows/ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6"
    },
    "usernamePassword.check" : {
      "href" : "https://auth.pingone.com/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/flows/ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6"
    },
    "user.register" : {
      "href" : "https://auth.pingone.com/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/flows/ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6"
    },
    "password.forgot" : {
      "href" : "https://auth.pingone.com/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/flows/ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6"
    }
  },
  "id" : "ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6",
  "resumeUrl" : "https://auth.pingone.com/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/as/resume?flowId=ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6",
  "status" : "USERNAME_PASSWORD_REQUIRED",
  "createdAt" : "2019-06-04T21:52:34.866Z",
  "expiresAt" : "2019-06-04T22:07:35.724Z",
  "_embedded" : {
    "passwordPolicy" : {
      "excludesProfileData" : true,
      "notSimilarToCurrent" : true,
      "excludesCommonlyUsed" : true,
      "maxRepeatedCharacters" : 2,
      "minUniqueCharacters" : 5,
      "length" : {
        "min" : 8,
        "max" : 255
      },
      "minCharacters" : {
        "abcdefghijklmnopqrstuvwxyz" : 1,
        "ABCDEFGHIJKLMNOPQRSTUVWXYZ" : 1,
        "1234567890" : 1,
        "~!@#$%^&*()-_=+[]{}|;:,.<>/?" : 1
      },
      "history" : {
        "count" : 6,
        "retentionDays" : 365
      }
    },
    "socialProviders" : [ {
      "id" : "179a9005-6f26-4294-9388-fcb0e9323353",
      "name" : "Facebook",
      "type" : "FACEBOOK",
      "_links" : {
        "authenticate" : {
          "href" : "https://auth.pingone.com/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/rp/authenticate?providerId=179a9005-6f26-4294-9388-fcb0e9323353&flowId=ff50b02c-48dd-4fbf-9c6d-82e8cc9e70c6"
        }
      }
    } ]
  }
}