> ## Documentation Index
> Fetch the complete documentation index at: https://developer.bron.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

<Note>
  **Most users should not implement signing manually.** Use the [CLI](/sdk/cli), [TypeScript SDK](/sdk/typescript), [Go SDK](/sdk/golang), or [Python SDK](/sdk/python) — all of them handle JWT signing, key rotation, retries, and the error envelope for you.

  Read on only if you're writing a custom client in a language without a Bron SDK, or if you need direct control over the JWT lifecycle.
</Note>

```shell theme={"system"}
Authorization: ApiKey {jwt}
```

API Key authentication allows you to securely access the Bron API using cryptographic signatures.
This method uses [JSON Web Tokens (JWT)](https://jwt.io/introduction) to ensure both authentication and request integrity.

<Accordion title="What is JWT?" icon="lock">
  [JSON Web Tokens (JWT)](https://jwt.io/introduction) is an open standard for securely transmitting information between parties as a JSON object.

  A JWT consists of three parts separated by dots:

  | Part        | Contents                                                                      | Encoding            |
  | :---------- | :---------------------------------------------------------------------------- | :------------------ |
  | `Header`    | Metadata about the key id, signing algorithm and etc.                         | base64-encoded JSON |
  | `Payload`   | Claims (data) you want to transmit                                            | base64-encoded JSON |
  | `Signature` | Signature of `base64url(header) + "." + base64url(payload)` using private key | binary → base64url  |

  Example of the JWT:

  ```shell theme={"system"}
  eyJraWQiOiJCdWp0RjQwZlUyNXBGdlNabEdrQyIsImFsZyI6IkVTMjU2In0.eyJpYXQiOjE3NDkyMTI4NDQsIm1lc3NhZ2UiOiJhcnRlbS13YXMtaGVyZSJ9.NtTsKix0Fj6gXA9sSInfW9PRqO82RlLHyvY_ZKRkpof
  BeUHU8gsDnHP7_OjUeoB4nYHhsps1RLWFjzkyaJCkwQ
  ```

  |             |                                                                                          |
  | :---------- | :--------------------------------------------------------------------------------------- |
  | `Header`    | `eyJraWQiOiJCdWp0RjQwZlUyNXBGdlNabEdrQyIsImFsZyI6IkVTMjU2In0`                            |
  | `Payload`   | `eyJpYXQiOjE3NDkyMTI4NDQsIm1lc3NhZ2UiOiJhcnRlbS13YXMtaGVyZSJ9`                           |
  | `Signature` | `NtTsKix0Fj6gXA9sSInfW9PRqO82RlLHyvY_ZKRkpofBeUHU8gsDnHP7_OjUeoB4nYHhsps1RLWFjzkyaJCkwQ` |
</Accordion>

### Bron JWT Structure

<Tabs>
  <Tab title="Header">
    ```json theme={"system"}
    {
      "alg": "ES256",
      "kid": "your-api-key-id"
    }
    ```

    | Field | Description                                |
    | :---- | :----------------------------------------- |
    | `alg` | Signing algorithm                          |
    | `kid` | Your API key identity ID from the Bron App |
  </Tab>

  <Tab title="Payload">
    ```json theme={"system"}
    {
      "message": "sha256_hash_of_request_data",
      "iat": 1749135506
    }
    ```

    | Field     | Description                                                                                                    |
    | :-------- | :------------------------------------------------------------------------------------------------------------- |
    | `message` | SHA256 hash of the request data, fields separated by newlines (`\n`):<br />`"{iat}\n{METHOD}\n{PATH}\n{BODY}"` |
    | `iat`     | Issued At. Unix timestamp in seconds                                                                           |
  </Tab>
</Tabs>

## Step-by-Step Implementation

<Steps>
  <Step title="Prepare Your Credentials">
    * Generate or upload your API Key in the Bron App and obtain your API Key ID
    * Save your private key securely
    * Use your API Key ID (`kid`) in the JWT header.
  </Step>

  <Step title="Create the Message String">
    Concatenate these values separated by newline (`\n`) characters:

    ```
    {iat}\n{HTTP_METHOD}\n{REQUEST_PATH}\n{REQUEST_BODY}
    ```

    **Components:**

    |                |                                                                                   |
    | :------------- | :-------------------------------------------------------------------------------- |
    | `iat`          | Current timestamp in seconds (same value used in JWT payload)                     |
    | `HTTP_METHOD`  | HTTP method in uppercase (GET, POST, PUT, DELETE)                                 |
    | `REQUEST_PATH` | Full request path including query parameters<br />(e.g. `/api/v1/users?limit=10`) |
    | `REQUEST_BODY` | JSON string exactly as sent (empty string if none)                                |

    **Example:**

    ```
    1749217170\nPOST\n/workspaces/bron/transactions\n{"transactionType":"swap","params":{"amount":"1"}}
    ```
  </Step>

  <Step title="Generate SHA256 Hash">
    Compute SHA256 over the message string. In Node.js:

    ```js theme={"system"}
    const crypto = require('crypto');
    const message = `${iat}\n${method}\n${path}\n${bodyString}`;
    const hash = crypto.createHash('sha256').update(message).digest('hex');
    ```

    Store that hex string in the JWT payload under `"message"`.
  </Step>

  <Step title="Sign the JWT">
    Create and sign the JWT using your private key
  </Step>
</Steps>

## Examples

<Tabs>
  <Tab title="GET">
    Request:

    ```shell theme={"system"}
    GET https://api.bron.org/workspaces/bron
    ```

    JWT Header:

    ```json theme={"system"}
    {
      "kid": "BujtF40fU25pFvSZlGkC",
      "alg": "ES256"
    }
    ```

    |               |                                                                    |
    | :------------ | :----------------------------------------------------------------- |
    | `Time`        | `1749219350`                                                       |
    | `Message`     | `1749219350\nGET\n/workspaces/bron\n`                              |
    | `SHA256 Hash` | `998371af53740a6cb4f13a7111f8e1b9f12063f8451d2a5b270be8f073b03505` |

    JWT Payload

    ```json theme={"system"}
    {
      "iat": 1749219350,
      "message": "998371af53740a6cb4f13a7111f8e1b9f12063f8451d2a5b270be8f073b03505"
    }
    ```

    Signed JWT:

    ```
    eyJraWQiOiJCdWp0RjQwZlUyNXBGdlNabEdrQyIsImFsZyI6IkVTMjU2In0.eyJpYXQiOjE3NDkyMTkzNTAsIm1lc3NhZ2UiOiIyNWU3ODNiOTc4ZWIwNTllZjRlY2UwMjcxOThlOTc0YTFlZjdmMDA2MDhmNTAzM2UxMDFhMWI5NTZiNmM4YWNkIn0.lDtT1sD4JUsjaIczcpgiT8xAn8hZnnX_dg_ut8t8tsz-JWHGJBnwCMNs3OgFrR_77r3EDZCuoiB7W_FKPbNpsw
    ```

    Authorization Header:

    ```shell theme={"system"}
    Authorization: ApiKey eyJraWQiOiJCdWp0RjQwZlUyNXBGdlNabEdrQyIsImFsZyI6IkVTMjU2In0.eyJpYXQiOjE3NDkyMTkzNTAsIm1lc3NhZ2UiOiIyNWU3ODNiOTc4ZWIwNTllZjRlY2UwMjcxOThlOTc0YTFlZjdmMDA2MDhmNTAzM2UxMDFhMWI5NTZiNmM4YWNkIn0.lDtT1sD4JUsjaIczcpgiT8xAn8hZnnX_dg_ut8t8tsz-JWHGJBnwCMNs3OgFrR_77r3EDZCuoiB7W_FKPbNpsw
    ```
  </Tab>

  <Tab title="POST">
    Request:

    ```shell theme={"system"}
    POST https://api.bron.org/workspaces/bron/transactions
    ```

    JWT Header:

    ```json theme={"system"}
    {
      "kid": "BujtF40fU25pFvSZlGkC",
      "alg": "ES256"
    }
    ```

    |               |                                                                                                                                          |
    | :------------ | :--------------------------------------------------------------------------------------------------------------------------------------- |
    | `Time`        | `1749219587`                                                                                                                             |
    | `Message`     | `1749219587\nPOST\n/workspaces/bron/transactions\n{`<br />`    "transactionType": "swap",`<br />`    "params": {"amount": "1"}`<br />`}` |
    | `SHA256 Hash` | `8a052df815d689679093720e2ba23d5a7c033d5c1fb81f0c3a1c23e03d809326`                                                                       |

    JWT Payload

    ```json theme={"system"}
    {
      "iat": 1749219587,
      "message": "19e3dee8b33cf9dbe5ee09acd9993380432876a2412ef741b05f8b2ac3672460"
    }
    ```

    Signed JWT:

    ```
    eyJraWQiOiJCdWp0RjQwZlUyNXBGdlNabEdrQyIsImFsZyI6IkVTMjU2In0.eyJpYXQiOjE3NDkyMTk1ODcsIm1lc3NhZ2UiOiIxOWUzZGVlOGIzM2NmOWRiZTVlZTA5YWNkOTk5MzM4MDQzMjg3NmEyNDEyZWY3NDFiMDVmOGIyYWMzNjcyNDYwIn0.eGlmLqqefLaHdl1w9LmdKmhDZCREL439_VdVdaQv_GDLVotOSD5PXthisG8cddLbRQ1pKUKvcFcFZDBPF0P53Q
    ```

    Authorization Header:

    ```shell theme={"system"}
    Authorization: ApiKey eyJraWQiOiJCdWp0RjQwZlUyNXBGdlNabEdrQyIsImFsZyI6IkVTMjU2In0.eyJpYXQiOjE3NDkyMTk1ODcsIm1lc3NhZ2UiOiIxOWUzZGVlOGIzM2NmOWRiZTVlZTA5YWNkOTk5MzM4MDQzMjg3NmEyNDEyZWY3NDFiMDVmOGIyYWMzNjcyNDYwIn0.eGlmLqqefLaHdl1w9LmdKmhDZCREL439_VdVdaQv_GDLVotOSD5PXthisG8cddLbRQ1pKUKvcFcFZDBPF0P53Q
    ```
  </Tab>
</Tabs>