HTTP Connection & Authorization

The API system is designed to operate across 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"   (An initial Access Token might not be provided, as you can generate one yourself using the Refresh Token).

These credentials are private and will be provided by the Hyper System Administrator upon initial setup.
You can manage the API settings and tokens via the Hyper Client App (Control Panel).

Request Flow & Security Verification

When a request is sent to the API, it goes through several security and verification layers before processing the main data:
  • Health Check: Calling the alive_check endpoint bypasses other security checks and immediately returns a success status. This is mainly used for external monitoring systems.
  • IP Whitelisting: The system verifies if your IP address is authorized to access the API. If your IP is not on the list, it returns HTTP 403 (Forbidden).
  • Blocked Functions: The system checks if the specific requested endpoint is administratively blocked. If blocked, it returns HTTP 403 (Forbidden).
  • Authorization: Validates the Bearer token provided in the header. If missing or expired, it returns HTTP 401 (Unauthorized).
  • Rate Limiting (IP Flooding): To prevent abuse, the system limits the number of requests per minute per IP (e.g., typically 20 requests per minute for API mode, unless configured differently in the Hyper Client App). Exceeding this limit returns HTTP 429 (Too Many Requests).

Tokens

There are two types of tokens:
  • Access Token - used as a "BEARER TOKEN" in every API call.
    This is a 120-character token that has a default validity of 1 Hour. This duration can be configured in the Hyper Client App.
  • Refresh Token - used as a "BEARER TOKEN" to regenerate an Access Token that expired.
    This is a 200-character token that does not expire automatically. This token can be re-generated only in the Hyper Client App.

Token Expired Example

This example demonstrates an API call payload used to search for an 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 GlmxIAtW3TxoNfq7t3Rj...
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 sent with a WRONG Access Token.
The returned result: 
{
  "Authorization": "False",
  "Message": "Missing / Wrong Access Token."
}

Check for Token Validity

To check the remaining validity of your Access Token, call the TokenValidity endpoint without parameters, using your Access Token as the Bearer token.
You may use HTTP GET or POST, both will work the same.

Here is an example result: 
{
  "Token Valid Until UTC": "2024-12-31 00:00:00",
  "Last Refresh Time UTC": "2024-02-07 14:57:15"
}
If the token has expired, it will result as the "Token Expired Example" above.

How to Refresh Access Tokens

Call the RefreshToken endpoint without parameters, using your Refresh Token as the Bearer token.
You may use HTTP GET or POST, it will work the same.

Here is an example: 
GET /RefreshToken HTTP/1.1
Host: {{Access URL}}
Authorization: Bearer e0usqefx1U52k62VoFOe8...

The returned result: 
{
  "access_token": "cEhuju6Nn...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Grace Period & Concurrency

After successfully calling the RefreshToken function, the API system will continue to accept the previous token for 3 minutes (Grace Period).
This allows active connections and multi-threaded applications to finish their work smoothly, and gives you a window to retry in case of an error on your side.

Note: Calling the RefreshToken endpoint multiple times within a 30-minute window will not generate a new token.
Instead, the API will return the currently active Access Token to prevent database overload.

Rate Limiting & IP Flooding Protection

To ensure stability and prevent abuse or accidental overloads, Hyper API includes a built-in Web Application Firewall (WAF) that monitors the rate of incoming requests.

Here is how the IP Flooding mechanism works:
  • Traffic Monitoring: The system counts the number of data requests coming from your specific IP address within a 60-second window.
  • Dynamic Thresholds: The maximum allowed requests per minute is determined by your API profile settings (configured via Hyper Client App). Otherwise, the default limit is 20 requests per minute.
  • Exceeding the Limit: If your application sends more requests than the allowed limit within a single minute, the API will temporarily block further processing from your IP.
  • HTTP 429 Response: When blocked, the system returns an HTTP Status Code 429 Too Many Requests.
  • Retry-After Header: Along with the 429 status, the response headers will include a Retry-After value. This indicates the exact number of seconds your application must wait before the 60-second window resets and accepts new requests.

Handling Rate Limits in Your Code

It is considered a best practice to design your application to handle HTTP 429 responses gracefully.
When you receive this status, your code should read the Retry-After header, pause execution for the specified amount of seconds, and then retry the request.

Example response of a blocked request: 
HTTP/1.1 429 Too Many Requests
Content-Type: text/html
Retry-After: 15

Too Many Requests, Don't abuse the server, Retry in: 15 seconds.