Skip to main content

​
Overview

Crown API uses JWT (JSON Web Token) authentication to secure all API endpoints. Every request must include a valid JWT token in the Authorization header.
Self-Signed JWT Tokens: Unlike traditional APIs where tokens are issued by the third party, Crown API requires you to generate and sign JWT tokens using your private key on your server-side. This approach provides enhanced security by ensuring only you have control over token creation.

​
Required Headers

All authenticated requests must include these headers: 
X-API-Key: your_api_key_here
Authorization: Bearer your_jwt_token_here
Content-Type: application/json

​
JWT Structure

Your JWT token must contain the following payload: 
{
  "uri": "/api/v1/endpoint",
  "nonce": "unique_request_identifier",
  "iat": 1640995200,
  "exp": 1640995230,
  "sub": "your_api_key",
  "bodyHash": "sha256_hash_of_request_body"
}

​
JWT Payload Fields

​
uri
string
required
The API endpoint path you’re requesting
​
nonce
string
required
A unique identifier for this request. Must be different for each API call.
​
iat
number
required
Token issued at time (Unix timestamp)
​
exp
number
required
Token expiration time (Unix timestamp).
​
sub
string
required
Your API key identifier
​
bodyHash
string
required
SHA-256 hash of the request body. Use empty string hash for GET requests.

​
Signing Your JWT

Sign your JWT using the RS256 algorithm with your private key: 
const jwt = require('jsonwebtoken');
const crypto = require('crypto');
const requestBody = {message: "Hello World"}

// Create payload
const payload = {
  uri: '/api/v1/echo',
  nonce: crypto.randomUUID(),
  iat: Math.floor(Date.now() / 1000),
  exp: Math.floor(Date.now() / 1000) + 50,
  sub: 'your_api_key',
  bodyHash: crypto.createHash('sha256').update(JSON.stringify(requestBody)).digest('hex')
};

// Sign JWT
const token = jwt.sign(payload, privateKey, { algorithm: 'RS256' });

​
Making Authenticated Requests

For comprehensive authentication examples and implementations, check out our authentication examples repository. You’ll find complete working examples in multiple languages including JavaScript, Python, Go, and others.

​
Security Best Practices

Keep your private key secure and never expose it in client-side code or public repositories.
  • Unique Nonces: Always generate a unique nonce for each request
  • Short Expiration: Keep JWT expiration within 50 seconds
  • Secure Storage: Store your private key securely
  • Body Hashing: Always include the correct body hash, even for empty bodies

​
Error Responses

Authentication failures will return a 401 Unauthorized