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 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 | REQUIRED. Value Must be OpenAPIV2 |
sub | string | REQUIRED. Your API Key |
nonce | string | REQUIRED. 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_window | string | OPTIONAL. 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.