Authorization API

This chapter describes the REST API used to implement the user authorization mentioned in the "OAuth2-based Authorization" and "Authorization Streams" sections.

Start Authorization (Auth Endpoint)
REQUEST
URI: https://login.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/auth
Sandbox URI: https://login-sandbox.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/auth
Parameters:
response_type - REQUIRED. This value is code.
client_id - REQUIRED. Client Identifier.
redirect_uri - REQUIRED. Redirection URI to which the response will be sent.
scope - OPTIONAL. Requests may contain the openid scope value. Other scope values MAY be present.
flow_mode - OPTIONAL. (See ‘Authorization flows’ for details)
ui_locales - OPTIONAL. Preferred languages for the user interface.
login_hint - OPTIONAL. Hint to the Authorization Server about the login identifier.
verification_level - OPTIONAL.
verification_level - OPTIONAL.
​
This field can take the following values:
4 - KYC Full Verification (Identity documents, Proof of address, Phone verification, Selfie)
3 - KYC Basic (Identity documents, Phone verification, Selfie)
2 - Social (Twitter, Telegram). To start social verification, the scope parameter MUST contain twitter-check or telegram-check scopes
An example:
GET /auth/realms/HyperID/protocol/openid-connect/auth?
response_type=code
&client_id=client0
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&scope=openid%20telegram-check
&flow_mode=0
&ui_locales=en
&[email protected]
&verification_level=2
Response
Parameters:
locale - Languages of the user interface.
code - Access Code.
An example:
HTTP/1.1 302 Found
Location: https://client.example.org/cb?
     locale=en
     &code=code0
Exchange of Access Code for tokens (Token Endpoint)
Request
URI: https://login.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/token
Sandbox URI: https://login-sandbox.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded
Parameters:
grant_type - REQUIRED. This value is authorization_code.
code - REQUIRED. Authorization Code
redirect_uri - REQUIRED. Redirection URI to which the response with Authorization Code was sent.
client_id - REQUIRED. Client Identifier.
client_secret - REQUIRED. Client secret.

An example:
POST /auth/realms/HyperID/protocol/openid-connect/token HTTP/1.1
Host: login.hypersecureid.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code=code0
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&client_id=client0
&client_secret=secret0
Response
Parameters:
refresh_expires_in - Refresh token expiration interval in seconds
refresh_token - Refresh token
expires_in - Access token expiration interval in seconds
access_token - Access token
An example:
HTTP/1.1 200 OK
Content-Type: application/json
{
   "refresh_expires_in": 2589446,
   "refresh_token": "AA.BB.CC",
   "expires_in": 3599,
   "access_token": "DD.EE.FF"
}
Token re-issuance (Token Endpoint)
Request
URI: https://login.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/token
Sandbox URI: https://login-sandbox.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded
Parameters:
grant_type - REQUIRED. This value is refresh_token.
refresh_token - REQUIRED. Refresh token
client_id - REQUIRED. Client Identifier.
client_secret - REQUIRED. Client secret.
An example:
POST /auth/realms/HyperID/protocol/openid-connect/token HTTP/1.1
Host: login.hypersecureid.com
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&refresh_token=AA.BB.CC
&client_id=client0
&client_secret=secret0
Response
Parameters:
refresh_expires_in - Refresh token expiration interval in seconds
refresh_token - Refresh token
expires_in - Access token expiration interval in seconds
access_token - Access token
An example:
HTTP/1.1 200 OK
Content-Type: application/json
{
   "refresh_expires_in": 2589446,
   "refresh_token": "AA.BB.CC",
   "expires_in": 3599,
   "access_token": "DD.EE.FF"
}
Token validation (Token Introspection Endpoint)
Request
URI: https://login.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/token/introspect
Sandbox URI: https://login-sandbox.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/token/introspect
Content-Type: application/x-www-form-urlencoded
Parameters:
token_type_hint - REQUIRED. This value is access_token
token - REQUIRED. Access token
client_id - REQUIRED. Client Identifier
client_secret - REQUIRED. Client secret
An example:
POST /auth/realms/HyperID/protocol/openid-connect/token/introspect HTTP/1.1
Host: login.hypersecureid.com
Content-Type: application/x-www-form-urlencoded
token_type_hint=access_token
&token=DD.EE.FF
&client_id=client0
&client_secret=secret0
Response
An example for an invalid token:
HTTP/1.1 200 OK
Content-Type: application/json
{
   "active": false
}
An example for a valid token:
HTTP/1.1 200 OK
Content-Type: application/json
{
      "exp":1653565113,
      "iat":1653564993,
      "auth_time":1653560464,
      "iss":"https://login.hypersecureid.com/auth/realms/HyperID",
      "sub":"userID",
      "typ":"Bearer",
      "azp":"clientID",
      "email":"[email protected]",
      "email_verified":true,
      "scope":"email",
      "active":true
}
Sign out (End Session Endpoint)
Request
URI: https://login.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/logout
Sandbox URI:
https://login-sandbox.hypersecureid.com/auth/realms/HyperID/protocol/openid-connect/logout
Content-Type: application/x-www-form-urlencoded
Parameters:
refresh_token - REQUIRED. Refresh token
client_id - REQUIRED. Client Identifier.
client_secret - REQUIRED. Client secret
An example:
POST /auth/realms/HyperID/protocol/openid-connect/logout HTTP/1.1
Host: login.hypersecureid.com
Content-Type: application/x-www-form-urlencoded
refresh_token=AA.BB.CC
&client_id=client0
&client_secret=secret0
​

API Documentation - Previous

Client Authentication

Next - API Documentation

Tokens

Last modified 23d ago