V3

Authentication

This document is a guidance of the authentication for BigONE Developer API.

BigONE Developer APIs fall into public APIs and private APIs. As for private API, developers have to offer token in header for BigONE to verify the user identity:

curl "https://API_SERVER/viewer/accounts" \
     -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiT3BlbkFQSVYyIiwic3ViIjoiY2VlODhhYjAtYmM2OS00MzU3LTg0YjctZGIwNTQ1ZTg1NjQ3Iiwibm9uY2UiOiIxNTI3NjY1MjYyMTY4MzkxMDAwIiwicmVjdl93aW5kb3ciOiI1MCJ9.AwsojrjKuQGTgmmkLDZ3piCOmuAQ_Y2PtU9JSUOQaT0'

How to get API Key and API Secret

Developers can set up API Key and API Secret in BigONE setting page.

Notice: The old private key is not compatible with OpenAPI V3 and a new private key must be generated.

Set up your token

BigONE API uses JSON Web Tokens (JWT) to make sure the request is authorized.

You need a JWT library for your language that supports the HS256 algorithm and the claims type MapClaim.

The JWT header

Make sure that the JWT's header conforms to the following constraints:

JWT Header Claimstypevalue
algstringHS256
typstringJWT

The JWT payload

Make sure that the JWT was signed by your own API Secret and the JWT payload conforms the following constraints:

JWT Payload Claimstypevalue
typestringREQUIRED. Value Must be OpenAPIV2
substringREQUIRED. Your API Key
noncestringREQUIRED. Must be a timestamp converted to a string. And the differential time between nonce and current timestamp must less than seconds that recv_window set. This timestamp is measured in nanoseconds since the UNIX epoch., e.g. 1527665262168391000.
recv_windowstringOPTIONAL. The seconds Allowed timestamp offset. Deafult value is 30.

Example

JWT Header

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

JWT Payload

{
  "type": "OpenAPIV2",
  "sub": "cee88ab0-bc69-4357-84b7-db0545e85647",
  "nonce": "1527665262168391000",
  "recv_window": "50"
}

Use testsecret as the secret to sign you token

Notice: DO NOT encode your secret using Base64, otherwise the token would be invalid.

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoiT3BlbkFQSVYyIiwic3ViIjoiY2VlODhhYjAtYmM2OS00MzU3LTg0YjctZGIwNTQ1ZTg1NjQ3Iiwibm9uY2UiOiIxNTI3NjY1MjYyMTY4MzkxMDAwIiwicmVjdl93aW5kb3ciOiI1MCJ9.wuOfj7xmBN7o_TZ9mT4kj0PdZ6qovFkkjEn4WWa7YII

For detailed definitions of error codes, you can see it here and also generate and parse your own token in this website.

← OverviewRate Limit →