> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crown-brlv.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  **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.
</Note>

## Required Headers

All authenticated requests must include these headers:

```http theme={null}
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:

```json theme={null}
{
  "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

<ParamField path="uri" type="string" required>
  The API endpoint path you're requesting
</ParamField>

<ParamField path="nonce" type="string" required>
  A unique identifier for this request. Must be different for each API call.
</ParamField>

<ParamField path="iat" type="number" required>
  Token issued at time (Unix timestamp)
</ParamField>

<ParamField path="exp" type="number" required>
  Token expiration time (Unix timestamp).
</ParamField>

<ParamField path="sub" type="string" required>
  Your API key identifier
</ParamField>

<ParamField path="bodyHash" type="string" required>
  SHA-256 hash of the request body. Use empty string hash for GET requests.
</ParamField>

## Signing Your JWT

Sign your JWT using the **RS256** algorithm with your private key:

<CodeGroup>
  ```javascript JavaScript theme={null}
  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' });
  ```
</CodeGroup>

## Making Authenticated Requests

For comprehensive authentication examples and implementations, check out our [authentication examples repository](https://github.com/crown-xyz/crown-developer-hub/tree/main/examples/api-authentication). You'll find complete working examples in multiple languages including [JavaScript](https://github.com/crown-xyz/crown-developer-hub/tree/main/examples/api-authentication/javascript), Python, Go, and others.

## Security Best Practices

<Warning>
  Keep your private key secure and never expose it in client-side code or public repositories.
</Warning>

* **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`