Creating an Authorized Request

Make a REST API Request

REST API calls are made over HTTP.

For POST, PUT, and DELETE requests, set JSON format. An example of the valid content type is as follows and may vary by programming language or library:

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

❗️
v1.3.0 Updates : End of support for urlencoded-form (March 2022)
From March 2022, HTTP request using the urlencoded form body was deprecated.
Please use JSON format instead.
See the detailed information in the notice.

Generate an 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 acccess 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 March 2022, the JWT payload generated with the query field was deprecated. Please use query_hash and query_hash_alg fields instead.
Please see the detailed information in the notice.

🚧
The query value to generate the query_hash value of the payload must use 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.

(Example) If there are no parameters,

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

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

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

# Python 3

import jwt   # PyJWT 
import uuid

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

jwt_token = jwt.encode(payload, 'Issued Secret Key')
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: 'Issued Access key',
    nonce: SecureRandom.uuid,
}

jwt_token = JWT.encode(payload, 'Issued 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 = "Issued Access key";
        String secretKey = "Issued 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", "Issued Access Key" },
            { "nonce", Guid.NewGuid().ToString() },
            { "query_hash", queryHash },
            { "query_hash_alg", "SHA512" }
        };

        byte[] keyBytes = Encoding.Default.GetBytes("Issued 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;
    }
}

(Example) If there are parameters

Whether you are delivering through an HTTP query string or delivering through the body, you must set query_hash value in the JWT payload.

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

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

Please note that the token verification may not pass if you make a request in a different format

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: "Issued Access key",
  nonce: uuidv4(),
  query_hash: queryHash,
  query_hash_alg: 'SHA512',
};

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

# Python 3

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

# query is a dict type.
m = hashlib.sha512()
m.update(urlencode(query).encode())
query_hash = m.hexdigest()

payload = {
    'access_key': 'Issued Access Key',
    'nonce': str(uuid.uuid4()),
    'query_hash': query_hash,
    'query_hash_alg': 'SHA512',
}
    
jwt_token = jwt.encode(payload, 'Issued Secret Key')
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 = {} #Parameter

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

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

jwt_token = JWT.encode(payload, 'Issued 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 = "Issued Access key";
        String secretKey = "Issued Secret key";

        String queryString = "Issue 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() {
        // If parameter is Dictionary<string, string>
        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", "Issued Access Key" },
            { "nonce", Guid.NewGuid().ToString() },
            { "query_hash", queryHash },
            { "query_hash_alg", "SHA512" }
        };

        byte[] keyBytes = Encoding.Default.GetBytes("Issued 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;
    }
}

Creating an Authorized Request

Make a REST API Request

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

Generate an Authorization Token (JWT)

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

🚧

🚧

(Example) If there are no parameters,

(Example) If there are parameters

Make a REST API Request

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

Generate an Authorization Token (JWT)

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

🚧

🚧

(Example) If there are no parameters,

(Example) If there are parameters

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

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