AnnouncementsGuidesAPI ReferenceSupport

Creating an Authorizable Request

Suggest Edits

Make a REST API Request

For POST, PUT, and DELETE requests, set the HTTP body value as JSON format if exists. An example of the valid content type is:

Content-Type: application/json; charset=utf-8

Content types may have some differences for each programming language or library.

❗️

v1.3.0 Updates : End of support for urlencoded-form (March 2022)

From March 2022, HTTP requests using the urlencoded form body will be deprecated. Please use JSON format instead.

Generate a Authorization Token (JWT)

To make a REST API request, generate a token using the access_key and secret_key, then add it to the Authorization header. The token follows the JWT format (https://jwt.io).

The recommended signature method is HS256. Use the secret key to sign the token. The payload configuration is as follows.

{
	"access_key": "Issued Access Key (Required)",
  "nonce": "Random UUID String (Required)",
  "query_hash": "Hashed Query String (required if there are parameters)",
	"query_hash_alg": "Algorithm used to generate query_hash (Default value: SHA512)"
}

❗️

v1.3.0 Updates: End of support for legacy authorization methods (March 2022)

From Match 2022, JWT payload generated with query field will be deprecated. Please use query_hash and query_hash_alg fields instead.

🚧

The query value to generate the "query_hash" value of the payload must use [query string] (https://en.wikipedia.org/wiki/Query_string). JSON and other formats are not permitted.

🚧

The issued secret key is not base64 encoded. Please check related options if you are using a library to handle JWT values.

If there are no parameters,

const jwt = require("jsonwebtoken");
const uuidv4 = require("uuid/v4");

const payload = {
  access_key: "Access key",
  nonce: uuidv4(),
};

const jwtToken = jwt.sign(payload, "Secret key");
const authorizationToken = `Bearer ${jwtToken}`;

# Python 3

import jwt   # PyJWT 
import uuid

payload = {
    'access_key': 'Access Key',
    'nonce': str(uuid.uuid4()),
}

jwt_token = jwt.encode(payload, 'Secret Key',).decode('utf8')
authorization_token = 'Bearer {}'.format(jwt_token)

#!/usr/bin/env ruby

require 'securerandom'
require 'bundler/inline'
gemfile do
  source 'https://rubygems.org'
  gem 'jwt'
end

payload = {
    access_key: 'Access key',
    nonce: SecureRandom.uuid,
}

jwt_token = JWT.encode(payload, 'Secret key', 'HS256')
authorize_token = "Bearer #{jwt_token}"

import com.auth0.jwt.JWT;
import com.auth0.jwt.algorithms.Algorithm;

import java.util.UUID;

public class OpenApiSample {

    public static void main(String[] args) {
        String accessKey = "Access key";
        String secretKey = "Secret key";

        Algorithm algorithm = Algorithm.HMAC256(secretKey);

        String jwtToken = JWT.create()
                             .withClaim("access_key", accessKey)
                             .withClaim("nonce", UUID.randomUUID().toString())
                             .sign(algorithm);

        String authenticationToken = "Bearer " + jwtToken;
    }
}

using System;
using System.Text;
using System.Collections.Generic;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Cryptography;

public class OpenAPISample {
    public static void Main() {
        var payload = new JwtPayload
        {
            { "access_key", "Access Key" },
            { "nonce", Guid.NewGuid().ToString() },
            { "query_hash", queryHash },
            { "query_hash_alg", "SHA512" }
        };

        byte[] keyBytes = Encoding.Default.GetBytes("Secret Key");
        var securityKey = new Microsoft.IdentityModel.Tokens.SymmetricSecurityKey(keyBytes);
        var credentials = new Microsoft.IdentityModel.Tokens.SigningCredentials(securityKey, "HS256");
        var header = new JwtHeader(credentials);
        var secToken = new JwtSecurityToken(header, payload);

        var jwtToken = new JwtSecurityTokenHandler().WriteToken(secToken);
        var authorizationToken = "Bearer " + jwtToken;
    }
}

If there are parameters,

Whether you are delivering through a URI query (GET, DELETE) or delivering through the HTTP body (POST, PUT), you must set them all in payload if there are any parameters.

If you have Array in your parameter datatypes, the proper query string type is as follows.

key[]=value1&key[]=value2 ...

If you make a request in a different format, please note that the token verification may not pass.

const jwt = require("jsonwebtoken");
const uuidv4 = require("uuid/v4");
const crypto = require('crypto');
const querystring = require("querystring");

const query = querystring.queryEncode({/* Parameters */});

const hash = crypto.createHash('sha512');
const queryHash = hash.update(query, 'utf-8').digest('hex');

const payload = {
  access_key: "Access key",
  nonce: uuidv4(),
  query_hash: queryHash,
  query_hash_alg: 'SHA512',
};

const jwtToken = jwt.sign(payload, "Secret key");
const authorizationToken = `Bearer ${jwtToken}`;

# Python 3

import jwt    # PyJWT 
import uuid
import hashlib
from urllib.parse import urlencode

m = hashlib.sha512()
m.update(urlencode(query).encode())
query_hash = m.hexdigest()

payload = {
    'access_key': 'Access Key',
    'nonce': str(uuid.uuid4()),
    'query_hash': query_hash,
    'query_hash_alg': 'SHA512',
}
    
jwt_token = jwt.encode(payload, 'Secret Key',).decode('utf8')
authorization_token = 'Bearer {}'.format(jwt_token)

#!/usr/bin/env ruby

require 'securerandom'
require 'bundler/inline'
gemfile do
  source 'https://rubygems.org'
  gem 'jwt'
end

params = {} 

query_string = URI.encode_www_form(params)
query_hash = Digest::SHA512.hexdigest(query_string)

payload = {
    access_key: 'Access key',
    nonce: SecureRandom.uuid,
    query_hash: query_hash,
    query_hash_alg: 'SHA512',
}

jwt_token = JWT.encode(payload, "Secret key', 'HS256')
authorize_token = "Bearer #{jwt_token}"

import com.auth0.jwt.JWT;
import com.auth0.jwt.algorithms.Algorithm;

import java.io.UnsupportedEncodingException;
import java.math.BigInteger;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.UUID;

public class OpenApiSample {

    public static void main(String[] args) throws NoSuchAlgorithmException, UnsupportedEncodingException {
        String accessKey = "Access key";
        String secretKey = "Secret key";

        String queryString = "query string";

        MessageDigest md = MessageDigest.getInstance("SHA-512");
        md.update(queryString.getBytes("utf8"));

        String queryHash = String.format("%0128x", new BigInteger(1, md.digest()));

        Algorithm algorithm = Algorithm.HMAC256(secretKey);
        String jwtToken = JWT.create()
                             .withClaim("access_key", accessKey)
                             .withClaim("nonce", UUID.randomUUID().toString())
                             .withClaim("query_hash", queryHash)
                             .withClaim("query_hash_alg", "SHA512")
                             .sign(algorithm);

        String authenticationToken = "Bearer " + jwtToken;
    }

}

using System;
using System.Text;
using System.Collections.Generic;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Cryptography;

public class OpenAPISample {
    public static void Main() {
        
        StringBuilder builder = new StringBuilder();
        foreach (KeyValuePair<string, string> pair in parameters)
        {
            builder.Append(pair.Key).Append("=").Append(pair.Value).Append("&");
        }
        string queryString = builder.ToString().TrimEnd('&');

        SHA512 sha512 = SHA512.Create();
        byte[] queryHashByteArray = sha512.ComputeHash(Encoding.UTF8.GetBytes(queryString));
        string queryHash = BitConverter.ToString(queryHashByteArray).Replace("-", "").ToLower();

        var payload = new JwtPayload
        {
            { "access_key", "Access Key" },
            { "nonce", Guid.NewGuid().ToString() },
            { "query_hash", queryHash },
            { "query_hash_alg", "SHA512" }
        };

        byte[] keyBytes = Encoding.Default.GetBytes("Secret Key");
        var securityKey = new Microsoft.IdentityModel.Tokens.SymmetricSecurityKey(keyBytes);
        var credentials = new Microsoft.IdentityModel.Tokens.SigningCredentials(securityKey, "HS256");
        var header = new JwtHeader(credentials);
        var secToken = new JwtSecurityToken(header, payload);

        var jwtToken = new JwtSecurityTokenHandler().WriteToken(secToken);
        var authorizationToken = "Bearer " + jwtToken;
    }
}

Updated about 2 years ago