API Authentication

Learn how to authenticate your API requests using JWT tokens

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:

JavaScript

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