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.eyJ0eXBlIjoiT3BlbkFQSSIsInN1YiI6ImNlZTg4YWIwYmM2OTQzNTc4NGI3ZGIwNTQ1ZTg1NjQ3Iiwibm9uY2UiOjE1Mjc2NjUyNjIxNjgzOTEwMDB9.YNpae4v_-OU7h2sknRPa3XPhDcC3p-To1WxbWV4Vpro'

How to get API Key and API Secret

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

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.

And DO NOT encode your signature using Base64, otherwise the token would be invalid.

The JWT header

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

JWT Header Claims	type	value
alg	string	HS256
typ	string	JWT

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 Claims	type	value
type	string	Must be OpenAPI
sub	string	Your API Key
nonce	number	Must be a timestamp. And the differential time between nonce and current timestamp must less than 30 seconds . This timestamp is measured in nanoseconds since the UNIX epoch., e.g. 1527665262168391000.

Example

JWT Header

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

JWT Payload

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

Use testsecret to sign:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiT3BlbkFQSSIsInN1YiI6ImNlZTg4YWIwYmM2OTQzNTc4NGI3ZGIwNTQ1ZTg1NjQ3Iiwibm9uY2UiOjE1Mjc2NjUyNjIxNjgzOTEwMDB9.YNpae4v_-OU7h2sknRPa3XPhDcC3p-To1WxbWV4Vpro

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