HTTP Connection & Authorization

The Hyper API system is designed to operate across multiple instances. Each instance provides a unique "Connection URL", intended for use by a specific external application.
To authenticate and connect to the Hyper API, you must provide the following credentials:
  • "Connection URL"
  • "Refresh Token"   (adhering to the OAuth / JWT standard).
  • "Access Token"   (If an initial Access Token is not provided, you can generate one using your Refresh Token).

These credentials are strictly confidential and will be securely provisioned by your Hyper System Administrator during the initial setup.
API settings and token management are accessible via the Hyper Client App (Control Panel).

Request Flow & Security Verification

When a request is sent to the API, it passes through several security and verification layers before the main data is processed:
  • Health Check: Invoking the alive_check endpoint bypasses standard security protocols and returns an immediate success status. This is primarily designed for external monitoring systems.
  • IP Whitelisting: The API verifies whether your IP address is authorized. Unauthorized IP addresses receive an HTTP 403 (Forbidden) response.
  • Blocked Functions: The system verifies that the requested endpoint is not administratively restricted. Blocked functions return an HTTP 403 (Forbidden) response.
  • Authorization: The API validates the Bearer token supplied in the request header. Missing or expired tokens result in an HTTP 401 (Unauthorized) response.
  • Rate Limiting (IP Flooding): To mitigate abuse, the system enforces a rate limit on requests per IP address per minute (defaulting to 20 requests per minute, unless customized in the Hyper Client App).
    Exceeding this threshold triggers an HTTP 429 (Too Many Requests) response. An extended explanation of the algorithm is found further down this page.

Tokens

The system utilizes two types of tokens:
  • Access Token: Used as a "Bearer" token in the Authorization header for every API call.
    This is a 120-character token with a default validity of 1 Hour. The expiration duration can be configured within the Hyper Client App (upto 8760 hours).
  • Refresh Token: Used as a "Bearer" token exclusively to regenerate an expired Access Token.
    This is a 200-character token that does not expire automatically. It can only be regenerated manually via the Hyper Client App.

Token Expired Example

This example demonstrates an API call payload used to search for an existing client, sent with an expired Access 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 response: 
{
  "Authorization": "False",
  "Message": "Token is no longer valid. Please call RefreshToken function."
}

Wrong Token Example

This example shows the response when an API call is made with an invalid or incorrect Access Token.
The returned response: 
{
  "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 in the Authorization header.
Both HTTP GET and POST methods are supported.

Example response: 
{
  "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, the API will return the "Token Expired" error shown above.

How to Refresh Access Tokens

Call the RefreshToken endpoint without parameters, providing your Refresh Token as the Bearer token.
Both HTTP GET and POST methods are supported.

Example request: 
GET /RefreshToken HTTP/1.1
Host: {{Access URL}}
Authorization: Bearer e0usqefx1U52k62VoFOe8...

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

Grace Period & Concurrency

After successfully calling the RefreshToken endpoint, the API will continue to accept the previous token for a 3-minute Grace Period.
This ensures that active connections and multi-threaded operations finish smoothly, providing a window to retry in case of network interruptions.

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 processing overhead.

Rate Limiting & IP Flooding Protection

To ensure system stability and prevent abuse or accidental overloads, the Hyper API features a built-in Web Application Firewall (WAF) that monitors request rates.

Here is how the IP Flooding mechanism operates:
  • Traffic Monitoring: The system counts the number of data requests originating from your specific IP address within a rolling 60-second window.
  • Dynamic Thresholds: The maximum allowed requests per minute is determined by your API profile settings (configured via the Hyper Client App). The default threshold is 20 requests per minute.
  • Exceeding the Limit: If your application exceeds the allowed limit within a single minute, the API will temporarily block further requests from your IP.
  • HTTP 429 Response: When rate-limited, 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 integer 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 best practice to design your application to handle HTTP 429 responses gracefully.
When this status is received, your code should read the Retry-After header, suspend execution for the specified duration, and then retry the request.

Example response for a rate-limited 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.