Token Retrieval

The process of obtaining Access and Refresh Tokens

The process of obtaining access and refresh tokens begins with user authentication. Developers initiate one of the HyperID authentication flows by redirecting the user to the HyperID authentication URI with the response_type parameter set to code.

Upon successful user authentication and consent, HyperID responds by returning code. The code can be exchanged for access and refresh tokens through the API call. This step is required to secure the authentication process and should be performed by your application's backend for enhanced security.

To illustrate the process, let's take a look at the following examples of HTTP requests and responses:

Request

POST /auth/realms/HyperID/protocol/openid-connect/token HTTP/1.1
Host: login.hypersecureid.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 176

grant_type=authorization_code
&code=your_authorization_code
&redirect_uri=https%253A%252F%252Fyourapp.com%252Fcb
&client_id=your_app_client_id
&client_secret=your_app_client_secret

As we mentioned earlier, the code is obtained from the authentication step, while the redirect_uri, client_id and client_secret are retrieved from your client's configuration settings (see the Client Registration chapter for details).

It's important to note that HyperID only accepts the redirect_uri specified in the client configuration and the one is used in the previous authentication step, otherwise no tokens will be issued.

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
   "refresh_expires_in": 2592000,
   "refresh_token": "JWT-encoded token",
   "expires_in": 3600,
   "access_token": "JWT-encoded token"
}

The response contains access and refresh tokens and their respective lifetimes.

Below are examples of implemented 'Obtain Tokens' requests:

cURL

curl --location 'https://login.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=your_authorization_code' \
--data-urlencode 'redirect_uri=https%3A%2F%2Fyourapp.com%2Fcb' \
--data-urlencode 'client_id=your_app_client_id' \
--data-urlencode 'client_secret=your_app_client_secret'

JavaScript

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");

var urlencoded = new URLSearchParams();
urlencoded.append("grant_type", "authorization_code");
urlencoded.append("code", "your_authorization_code");
urlencoded.append("redirect_uri", "https%3A%2F%2Fyourapp.com%2Fcb");
urlencoded.append("client_id", "your_app_client_id");
urlencoded.append("client_secret", "your_app_client_secret");

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: urlencoded,
  redirect: 'follow'
};

fetch("https://login.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/token", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

NodeJS

const axios = require('axios');
const qs = require('qs');
let data = qs.stringify({
  'grant_type': 'authorization_code',
  'code': 'your_authorization_code',
  'redirect_uri': 'https%3A%2F%2Fyourapp.com%2Fcb',
  'client_id': 'your_app_client_id',
  'client_secret': 'your_app_client_secret' 
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://login.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/token',
  headers: { 
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  data : data
};

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

Python

import http.client

conn = http.client.HTTPSConnection("login.hypersecureid.com")
payload = 'grant_type=authorization_code&code=your_authorization_code&redirect_uri=https%253A%252F%252Fyourapp.com%252Fcb&client_id=your_app_client_id&client_secret=your_app_client_secret'
headers = {
  'Content-Type': 'application/x-www-form-urlencoded'
}
conn.request("POST", "/auth/realms/HyperID/protocol/openid-connect/token", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

C#

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://login.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/token");
var collection = new List<KeyValuePair<string, string>>();
collection.Add(new("grant_type", "authorization_code"));
collection.Add(new("code", "your_authorization_code"));
collection.Add(new("redirect_uri", "https%3A%2F%2Fyourapp.com%2Fcb"));
collection.Add(new("client_id", "your_app_client_id"));
collection.Add(new("client_secret", "your_app_client_secret"));
var content = new FormUrlEncodedContent(collection);
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());