Authentication

This guide explains how to authenticate your API requests using JSON Web Tokens (JWT).

Overview

BigONE API uses JWT tokens for authentication. You need to:

1. Create a JWT token using your API Key and API Secret
2. Include the token in the Authorization header of your requests

curl "https://api.big.one/api/v3/viewer/accounts" \
     -H 'Authorization: Bearer <YOUR_TOKEN>'

JWT Token Structure

BigONE API utilizes JSON Web Tokens (JWT) with the HS256 algorithm.

warning

Do not Base64 encode your API Secret when signing the JWT; use your API Secret as-is. Base64 encoding will render the token invalid.

JWT Header

Claim	Type	Value
alg	string	"HS256"
typ	string	"JWT"

JWT Payload

Claim	Type	Required	Description
type	string	Yes	Must be OpenAPIV2
sub	string	Yes	Your API Key
nonce	string	Yes	Timestamp in nanoseconds (e.g., 1527665262168391000)
recv_window	string	No	Allowable timestamp offset in seconds. Default: 30

About Nonce

The nonce prevents replay attacks. The difference between nonce and the server's current timestamp must be less than recv_window seconds.

Examples

Token Components

Let's create a token with:

• API Key: 765fc50d-39e0-11f0-9669-5a69d7ba6f46
• API Secret: testsecret

Header:

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

Payload:

{
  "type": "OpenAPIV2",
  "sub": "765fc50d-39e0-11f0-9669-5a69d7ba6f46",
  "nonce": "1527665262168391000"
}

Signed Token:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoiT3BlbkFQSVYyIiwic3ViIjoiY2VlODhhYjBiYzY5NDM1Nzg0YjdkYjA1NDVlODU2NDciLCJub25jZSI6MTUyNzY2NTI2MjE2ODM5MTAwMH0.cJ_uPmDeIxEPbKb_Xi0YuCflt_kgok5lryPwDG-jrsM

You can verify your token at jwt.io

Python

import jwt
import time

# Your credentials from BigONE settings
API_KEY = 'your_api_key_here'
API_SECRET = 'your_api_secret_here'

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

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

# Sign the token
token = jwt.encode(payload, API_SECRET, algorithm="HS256")

print(f"Authorization: Bearer {token}")

Go

package main

import (
    "fmt"
    "time"
    "github.com/golang-jwt/jwt/v4"
)

func main() {
    apiKey := "your_api_key_here"
    apiSecret := "your_api_secret_here"
    
    // Generate nonce in nanoseconds
    nonce := fmt.Sprintf("%d", time.Now().UnixNano())
    
    // Create claims
    claims := jwt.MapClaims{
        "type":  "OpenAPIV2",
        "sub":   apiKey,
        "nonce": nonce,
    }
    
    // Create and sign token
    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
    signedToken, err := token.SignedString([]byte(apiSecret))
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Authorization: Bearer %s\n", signedToken)
}

JavaScript

const jwt = require('jsonwebtoken');

const API_KEY = 'your_api_key_here';
const API_SECRET = 'your_api_secret_here';

// Generate nonce in nanoseconds
const nonce = (BigInt(Date.now()) * BigInt(1000000)).toString();

// Create payload
const payload = {
    type: 'OpenAPIV2',
    sub: API_KEY,
    nonce: nonce,
};

// Sign token
const token = jwt.sign(payload, API_SECRET, { algorithm: 'HS256' });

console.log(`Authorization: Bearer ${token}`);

Making Authenticated Requests

Include the token in your request header:

curl -X GET "https://api.big.one/api/v3/viewer/accounts" \
     -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."

Authentication Errors

HTTP Status	Code	Message	Description
401	40004	Unauthorized	Missing or invalid Authorization header
401	40106	Invalid Token	JWT is malformed, has invalid signature, or has expired
400	40107	Unexpected request header	Authorization header format is incorrect
403	10403	Permission denied	API key lacks required scopes, or IP not in whitelist
404	10013	Resource not found	API key does not exist or has been revoked

Troubleshooting

Common Issues and Solutions

1. 40004 Unauthorized: Ensure you include Authorization: Bearer <token> header
2. 40106 Invalid Token:
   • Check that JWT is signed with your API Secret as-is (do not Base64 encode the secret)
   • Verify nonce is within recv_window (default 30 seconds)
3. 40107 Unexpected request header: Header format must be exactly Bearer <token> (one space)
4. 10403 Permission denied:
   • Check API key scopes at BigONE Settings
   • Verify your IP is in the whitelist
5. 10013 Resource not found: API key may have been deleted

Next Steps

• General Information — Rate limits and response formats
• Error Codes — Complete list of error codes