V3

Authentication

This document provides guidance on authentication for the BigONE Developer API.

BigONE Developer APIs are categorized into public APIs and private APIs. For private API access, developers must provide a token in the header to enable BigONE to verify the user's identity:

curl "https://API_SERVER/viewer/accounts" \
     -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiT3BlbkFQSSIsInN1YiI6ImNlZTg4YWIwYmM2OTQzNTc4NGI3ZGIwNTQ1ZTg1NjQ3Iiwibm9uY2UiOjE1Mjc2NjUyNjIxNjgzOTEwMDB9.YNpae4v_-OU7h2sknRPa3XPhDcC3p-To1WxbWV4Vpro'

Developers are required to include an Authorization header in their requests when accessing private APIs. The value of this header must follow the format Bearer {YOUR_TOKEN}.

How to Obtain an API Key and API Secret

Developers can generate an API Key and API Secret through the BigONE settings page.

Setting Up Your Token

BigONE API utilizes JSON Web Tokens (JWT) to ensure that requests are authorized.

You will need a JWT library compatible with your programming language that supports the HS256 algorithm and the MapClaim claims type.

Importantly, you should not encode your signature using Base64; doing so will render the token invalid.

JWT Header Requirements

Ensure that your JWT's header adheres to the following specifications:

JWT Header ClaimsTypeValue
algstring"HS256"
typstring"JWT"

JWT Payload Requirements

Your JWT must be signed with your API Secret, and its payload should meet the following specifications:

JWT Payload ClaimsTypeValue
typestringREQUIRED. The value must be OpenAPIV2.
substringREQUIRED. Your API Key.
noncestringREQUIRED. Must be a timestamp converted to a string. The difference between the nonce and the current timestamp must be less than the seconds set by recv_window. This timestamp is measured in nanoseconds since the UNIX epoch, e.g., 1527665262168391000.
recv_windowstringOPTIONAL. Specifies the allowable timestamp offset in seconds. The default value is 30.

Example

Let's say your API Key is cee88ab0bc69435784b7db0545e85647 and API Secret is testsecret.

JWT Header

{
  "typ": "JWT",
  "alg": "HS256"
}

Typically, the JWT Header is automatically set by the JWT SDK.

JWT Payload

{
  "type": "OpenAPIV2",
  "sub": "cee88ab0bc69435784b7db0545e85647",
  "nonce": "1527665262168391000"
}

Use your api secret to sign:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoiT3BlbkFQSVYyIiwic3ViIjoiY2VlODhhYjBiYzY5NDM1Nzg0YjdkYjA1NDVlODU2NDciLCJub25jZSI6MTUyNzY2NTI2MjE2ODM5MTAwMH0.cJ_uPmDeIxEPbKb_Xi0YuCflt_kgok5lryPwDG-jrsM

And you can verify the encoded signature in this Debugger

Here's an example Python script that generates a JWT token using the HS256 algorithm. This script assumes you have your API_KEY and API_SECRET ready, as these are necessary for generating the token. The nonce value is a timestamp in nanoseconds.

import jwt
import time

# Your API Key and API Secret from BigONE settings
API_KEY = 'your_api_key_here'
API_SECRET = 'your_api_secret_here'

# Generate a nonce: current timestamp in nanoseconds
nonce = int(time.time() * 1e9)

# JWT payload
payload = {
    "type": "OpenAPIV2",
    "sub": API_KEY,
    "nonce": str(nonce),
}

# Encode the JWT using HS256 algorithm
token = jwt.encode(payload, API_SECRET, algorithm="HS256")

print(f"Authorization: Bearer {token}")
← OverviewRate Limit →