Password - Initiation

Provisioning

The Password-Based Authentication Provisioning API is initiated by the user to establish a password-based credential. In response, the server issues a session ID, bearer token, and a follow-up URL. The user is required to send their chosen password in a subsequent request to the provided follow-up URL to complete the authentication process.

API Description

Method : GET

URL : https://{environment-url}/realms/{partner-id}/protocol/api/init

Parameters

Name	Type	Description
client_id*	String	A unique client id that is shared for each partner.
client_secret*	String	A unique key that is generated for each product configured for the partner.
type*	String	Type of the authentication password

200: OK

{
    "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/required-action",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1NGVjNDRjMC04NDk1LTQyMTAtOWNkOS0zOGQ2ZDAwNDhjODciLCJleGVjdXRpb24iOiJ2aWRhLXBhc3N3b3JkLXJlZ2lzdGVyIiwidGFiX2lkIjoiRHloR2ZLRkRxeWsiLCJuYmYiOjE3MDMwNjI0ODAsInNlc3Npb25fY29kZSI6Ikp3Z3ZfbXZLYTlVRDFLSjhMSE1UM1pxVlR3Qy1rb19yMnZSUFRWZnBYejgiLCJzZXNzaW9uX2lkZW50aWZpZXIiOiJEeWhHZktGRHF5ayIsImV4cCI6MTcwMzA2Mjc4MCwiaWF0IjoxNzAzMDYyNDgwLCJhdXRoX3Nlc3Npb25faWQiOiI1NGVjNDRjMC04NDk1LTQyMTAtOWNkOS0zOGQ2ZDAwNDhjODciLCJqdGkiOiJkZThjMWNkOS01NDFiLTRmNzEtOGZhNC1jZWQ0ZmE1YjQyODUifQ.vkJw9mWDU68qyp17BEEmk5Nyxb0perHNljjaOHSZcQw",
    "authType": "password",
    "sessionIdentifier": "DyhGfKFDqyk"
}

Curl

curl --location -g --request GET 'https://{environment-url}/realms/{partner-id}/protocol/api/init?client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&type=password'

Python

import requests

url = "https://{environment-url}/realms/{partner-id}/protocol/api/init?client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&type=password"

payload={}
headers = {}

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

print(response.text)

NodeJS

var axios = require('axios');

var config = {
  method: 'get',
  url: 'https://{environment-url}/realms/{partner-id}/protocol/api/init?client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&type=password',
  headers: { }
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://{environment-url}/realms/{partner-id}/protocol/api/init?client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&type=password")
  .method("GET", body)
  .build();
Response response = client.newCall(request).execute();

C#

var client = new RestClient("https://{environment-url}/realms/{partner-id}/protocol/api/init?client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&type=password");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://{environment-url}/realms/{partner-id}/protocol/api/init?client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3&type=password',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Success Response

{
    "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/required-action",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1NGVjNDRjMC04NDk1LTQyMTAtOWNkOS0zOGQ2ZDAwNDhjODciLCJleGVjdXRpb24iOiJ2aWRhLXBhc3N3b3JkLXJlZ2lzdGVyIiwidGFiX2lkIjoiRHloR2ZLRkRxeWsiLCJuYmYiOjE3MDMwNjI0ODAsInNlc3Npb25fY29kZSI6Ikp3Z3ZfbXZLYTlVRDFLSjhMSE1UM1pxVlR3Qy1rb19yMnZSUFRWZnBYejgiLCJzZXNzaW9uX2lkZW50aWZpZXIiOiJEeWhHZktGRHF5ayIsImV4cCI6MTcwMzA2Mjc4MCwiaWF0IjoxNzAzMDYyNDgwLCJhdXRoX3Nlc3Npb25faWQiOiI1NGVjNDRjMC04NDk1LTQyMTAtOWNkOS0zOGQ2ZDAwNDhjODciLCJqdGkiOiJkZThjMWNkOS01NDFiLTRmNzEtOGZhNC1jZWQ0ZmE1YjQyODUifQ.vkJw9mWDU68qyp17BEEmk5Nyxb0perHNljjaOHSZcQw",
    "authType": "password",
    "sessionIdentifier": "DyhGfKFDqyk"
}

Error Response

{
    "error": "invalid_request",
    "errorDescription": "Client ID invalid"
}

Response Schema

{
    "error": "{TYPE OF ERROR}",
    "errorDescription": "{REASONING FOR THE ERROR}"
}

For a complete list of error codes and their meanings, refer to the Error Scenarios section.

To complete the Password provisioning process, follow up by using the Password Provisioning Completion API.

Password Authentication API

The Password Authentication API is employed when a user intends to authenticate their identity using the password method. Upon initiating a request for authentication, the server will reply with a session ID, bearer token, and a challenge. The user must respond to this challenge by submitting the password they have chosen. The API will then validate this password against the credential stored during the provisioning phase.

API Description

Method : GET

URL : https://{environment-url}/realms/{partner-id}/protocol/api/init

Parameters

Name	Type	Description
credential_id*	String	credential id generated during the process of provisioning
client_id*	String	A unique client id that is shared for each partner.
client_secret*	String	A unique key that is generated for each product configured for the partner.
type*	String	Type of the authentication Eg: password

The Credential ID can be obtained by decoding the Signed JWT tokens received as the access token from the Password Completion API.

200: OK

{
    "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/authenticate",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI5Zjc4Y2I4MS0xMzVmLTQ0ZmYtYjEwYy02MDIzNGFiODI2NTkiLCJleGVjdXRpb24iOiIzNjNmZjlkNi1hODAxLTRiNDEtODRjNS1kZWZiOTcxMmY5NzAiLCJ0YWJfaWQiOiI3U1ZZeGgwZTdYayIsIm5iZiI6MTcwMzA2MzUzOCwic2Vzc2lvbl9jb2RlIjoiNXR0c2p6blRzMTAwQTR5VTcwYnRjSkx1amluS29KYldPTHVwdklsRXVlUSIsInNlc3Npb25faWRlbnRpZmllciI6IjdTVll4aDBlN1hrIiwiZXhwIjoxNzAzMDYzODM4LCJpYXQiOjE3MDMwNjM1MzgsImF1dGhfc2Vzc2lvbl9pZCI6IjlmNzhjYjgxLTEzNWYtNDRmZi1iMTBjLTYwMjM0YWI4MjY1OSIsImp0aSI6IjQ1MjMxZDJhLWYwMzMtNGRhZS1iMzhjLWUyYjU2YjMxMjk5ZiJ9.3xq96LZP34cWddY4pYFC1wafm3c7ujqPZaa8kJgFy2g",
    "authType": "password",
    "sessionIdentifier": "7SVYxh0e7Xk"
}

Curl

curl --location --request GET 'https://{environment-url}/realms/{partner-id}/protocol/api/init?type=password&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT30'

Python

import requests

url = "https://{environment-url}/realms/{partner-id}/protocol/api/init?type=password&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3"

payload={}
headers = {}

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

print(response.text)

NodeJS

var axios = require('axios');

var config = {
  method: 'get',
  url: 'https://{environment-url}/realms/{partner-id}/protocol/api/init?type=password&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3',
  headers: { }
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Java

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://{environment-url}/realms/{partner-id}/protocol/api/init?type=password&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3")
  .method("GET", body)
  .build();
Response response = client.newCall(request).execute();

C#

var client = new RestClient("https://{environment-url}/realms/{partner-id}/protocol/api/init?type=password&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT39");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://{environment-url}/realms/{partner-id}/protocol/api/init?type=password&client_id=api&client_secret=enESfot4PPpSWxTa74vR8D9nrW4UTtT3',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Success Response

{
    "uri": "https://{environment-url}/realms/{partner-id}/protocol/api/authenticate",
    "bearerToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI5Zjc4Y2I4MS0xMzVmLTQ0ZmYtYjEwYy02MDIzNGFiODI2NTkiLCJleGVjdXRpb24iOiIzNjNmZjlkNi1hODAxLTRiNDEtODRjNS1kZWZiOTcxMmY5NzAiLCJ0YWJfaWQiOiI3U1ZZeGgwZTdYayIsIm5iZiI6MTcwMzA2MzUzOCwic2Vzc2lvbl9jb2RlIjoiNXR0c2p6blRzMTAwQTR5VTcwYnRjSkx1amluS29KYldPTHVwdklsRXVlUSIsInNlc3Npb25faWRlbnRpZmllciI6IjdTVll4aDBlN1hrIiwiZXhwIjoxNzAzMDYzODM4LCJpYXQiOjE3MDMwNjM1MzgsImF1dGhfc2Vzc2lvbl9pZCI6IjlmNzhjYjgxLTEzNWYtNDRmZi1iMTBjLTYwMjM0YWI4MjY1OSIsImp0aSI6IjQ1MjMxZDJhLWYwMzMtNGRhZS1iMzhjLWUyYjU2YjMxMjk5ZiJ9.3xq96LZP34cWddY4pYFC1wafm3c7ujqPZaa8kJgFy2g",
    "authType": "password",
    "sessionIdentifier": "7SVYxh0e7Xk"
}

Error Response

{
    "error": "invalid_user_credentials",
    "errorDescription": "Unauthorized"
}

Response Schema

{
    "error": "{TYPE OF ERROR}",
    "errorDescription": "{REASONING FOR THE ERROR}"
}

For a complete list of error codes and their meanings, refer to the Error Scenarios section.

To complete the Password authentication process, follow up by using the Password Authentication Completion API.