1. Home
  2. Docs
  3. Private: Rali APIs
  4. API Authenitcation

API Authenitcation

OnQ API services require a JSON Web Token (JWT) for usage against authenticated endpoints. This document serves as a quick start guide for first-time users.

What is a JSON Web Tokens?

JSON Web Token (JWT) is a JSON-based open standard (RFC 7519) for passing claims between parties in a web application environment. The tokens are designed to be compact, URL-safe and usable especially in web browser single sign-on (SSO) context.

One of the best things about a JWT is that it is cryptographically signed and can be signed in a number of ways such as using HMAC shared secret and RSA public/private key pairs.

See https://jwt.io for more details on JWT and libraries to help generate them.

Getting Started with JWT

Things to check before you start:

You must have an onQ tenant setup and be an organization admin for that tenant.  This will give you access to the Admin Panel in order to get the API key and secret.

Steps to generating a JWT Token

  1. Access API Key and Secret
  2. Create JWT header with the following fields below:

Add the API key in the header to the kid field.

  "alg": "HS256",
  "typ": "JWT",
  "kid": "ONQ-xxxxxxxxxxxxxxxx"
  1. Generate the following payload:
Attribute Description Required Example
iss Issuer, this is the site that is issuing the token Yes https://yoursite.com
sub Subject, Logged in username Yes user@yoursite.com
exp Expiration, Time token will expire (minimum 10 mins) Yes 1356999524
iat Issued at time, Time token was created Yes 1356999524
aud Audience, onQ tenant url Yes https://yoursite.onq.io


  1. Sign the payload with the onQ API Secret using HMAC SHA256 algorithm.


Sample Code


$secret = "xxxxxxxxxxxxxxxxxx"; // API Secret

$token = array(
"iss" => "https://yoursite.com",
"aud" => “https://yoursite.onq.io”,
"sub" => "user@yoursite.com",
"iat" => 1356999524,
"exp" => 1356999524

$data = JWT::encode($token, $secret);


String key = “ONQ-xxxxxxxxxxxxxxx”; // API key
String secret = “xxxxxxxxxxxxxxxxxxxx”; // API secret
String subject = “user@yoursite.com”;
String issuer = “https://yoursite.com”;
String audience = “https://yoursite.onq.io”;

Map<String, Object> claims = new HashMap<>();

String token = Jwts.builder()

.setHeaderParam(JwsHeader.KEY_ID, key)
.setIssuedAt(new Date())
.signWith(SignatureAlgorithm.HS512, secret.getBytes("UTF-8"))


Was this article helpful to you? Yes No

How can we help?