Connection & Tokens

The API system is designed to be installed and work in multiple instances.
Each instance will have its own "Connection URL", intended to be used by a specific (external) application.

To connect to Hyper API you need to have the following:
  • "Connection URL"
  • "Refresh Token"   (like in Oauth / JWT standard).
  • "Access Token"   (This token may not be provided. You can get a new one by yourself).

All of which are private to you and will be provided by Hyper's system Admin upon first use.

Tokens

There are two types of tokens:
  • Access Token - used as a "BEARER TOKEN" in every API call.
    This is a 120 characters token that has a default validity of 1 Hour. Interval can be changed in Hyper's Client App.
  • Refresh Token - used as a "BEARER TOKEN" to regenerate an Access Token that expired.
    This is a 200 characters token that has no expiration time, but has 2 operational modes: replaceable & Non replaceable.
    • Replaceable: for increased security, the refresh token can be set to be renewed alongside with the Access Token, every time you call the "RefreshToken" procedure.
    • Non Replaceable: the refresh token can be set as fixed token (never changes).

Although these tokens are generated by Hyper API System automatically, it can be managed manually for the purposes of: Extend Validity Duration, Regenerate, Block & Delete by Hyper's Client App.

Connections

Before we demonstrate a connection example, you should be aware to the issue of managing multiple API Connections together (multi threads),
since Hyper API has a single Access Token that needs to be Regenerated (Refreshed) and stored on your side for future calls!

Token Expired Example

This example shows an API call data, searching for existing client.
it was sent with an expired Access Token, stored as the previous token.
POST /Does_Entity_Exist_Json HTTP/1.1
Host: {{Access URL}}
Authorization: Bearer GlmxIAtW3TxoNfq7t3Rj5XvAptEi8EkYsabKCu7MGZUWLyGeNKvrrcyS4VZxg4uLinFHXcxzigXNMWd9d1X7XeYFtJVcY6vkvwn8JQ9C11bZulYdjO00-qzx
Content-Length: 102
{
  "phone":0528888000,
  "email":Ozzy@company1.com,
  "idnumber":121212121
}

The returned Result:
{
  "Authorization":False,
  "Message":Token is no longer valid. Please call "RefreshToken" function.
}

Wrong Token Example

This example shows an API call data, searching for existing client.
it was sent with a WRONG Access Token, NOT stored as the previous token in the system.
POST /Does_Entity_Exist_Json HTTP/1.1
Host: {{Access URL}}
Authorization: Bearer RnoYPGtBGq5mnVEynwJMmM7RHDFjl8IColSLxIg3MvwJDDUehj9QZmjd2NPsT6oLblTS3Vh2rzWO8AHlj8PhsEyiTxI1UjlDWWUFdcVCwFgRZzWKuiUVI8ZY
Content-Length: 102
{
  "phone":0528800000,
  "email":Ozzy@company1.com,
  "idnumber":121212121
}

The returned result:
{
  "Authorization":False,
  "Message":Missing \/ Wrong Access Token.
}

How to Refresh Access Tokens

Just call the RefreshToken function, without parameters and use the "Refresh Token" as your Bearer.
You may use HTTP GET or POST, it will work the same.

Here is an example:
POST /RefreshToken HTTP/1.1
Host: {{Access URL}}
Authorization: Bearer e0usqefx1U52k62VoFOe8Md47eprE23WajsAFB1Iyum079RtTWvXrAYZg-FoPs9Vr4oLARw9-cErxkiwONSPVFwJfYJroc53V6LTcIF-rwcCnohpmsWq9qTXhOmnqHEtRKQ3BtyLcCqYQulJlTvfXQrbqYDF3ZUGUiCqDXzrlgbAiNpjL8j6zentT1wjCsE4Mf8ydjIC

The returned result:
{
  "access_token":cEhuju6Nn--qEfbw49OGY-zZILVHf5W5xBTB4KnEmcQ987TQOUzQAiJzW7K7Uybw91NcAQkVUWSReELwjc9l7DP6XlWRoz5XYobcv8S5WyGvcYs6FqO8XaTD,
  "token_type":Bearer,
  "expires_in":3600,
  "refresh_token":XUHbOZ3eibPyBAG67jadJt3GNWHnWeVjP7OuYRwdMXBrnxMmI5kaVJCLg-TL5-JAixCVzZQURhNsUjjRjrcdNDxxzfhqGzaDlmgTsBau7DUz1TBcoMiWaCGGHtkgzjoiXwIjpnn8jG6X3yOxbQ3uD9SBl3Xg96HbjGB9v8m9ryxIEirDxOIKpC9Drc-0doB-k8-SiIZW
}

Pay attention please

After sucessfuly calling the "RefreshToken" function you should be aware that:
  1. The result parameter "expires_in" displays the new expiry period in seconds, and is relevant to the "Access Token" and also maybe the "Refresh Token" (depending on the settings).
  2. After executing the "RefreshToken" call, the API system will continue to accept the previous tokens for 2 minutes (we consider this to be a "grace period"), which will allow:
    • Active connections to finish their work.
    • Execute the "RefreshToken" call again, in case of an error on your side.
    • The "RefreshToken" API call is limited to a maximum of 10 calls per minute (by our system's WAF).

Check for Token Validity

To find out how much time is left for the "Access Token", call the TokenValidity function without parameters, and use bearer "access_token" (like any other API call).
You may use HTTP GET or POST, both will work the same.

Here is an example:
{
  "Token Valid Until UTC":2024-12-31 00:00:00,
  "Last Refresh Time UTC":2024-02-07 14:57:15,
  "Refresh Method":Refresh Token is Constant
}

Or, if the token has expired, the function will result:
{
  "Authorization":False,
  "Message":Token is no longer valid. Please call RefreshToken function.
}