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

# Authenticate with the Heymarket API

> Create API Secrets, generate short-lived JWTs, and authenticate Heymarket API requests.

Every request to the Heymarket API must be authenticated. Heymarket supports two authentication methods:

* **API Secret JWT authentication.** Recommended for new integrations. Generate a short-lived JWT from an API Secret ID and API Secret Key, then send the JWT as a Bearer token.
* **Team API key authentication.** Legacy authentication for existing integrations. API key authentication is planned for deprecation.

## Create an API Secret

Log in to [Heymarket](https://app.heymarket.com) and go to **Settings > Integrations > API**.

Generate an API Secret and copy both values:

* **Secret ID**: Used as the JWT `iss` value.
* **Secret Key**: Used with the Secret ID to sign the JWT.

<Warning>
  The Secret Key is shown only when it is generated. Copy and store it securely before closing the dialog.
</Warning>

<Warning>
  Generate signed JWTs only from trusted server-side code. Do not expose your Secret ID, Secret Key, signed JWTs, or legacy API key in browser JavaScript, mobile apps, public repositories, logs, or screenshots.
</Warning>

## Generate a signed JWT

Use your API Secret ID and Secret Key to sign a short-lived JSON Web Token (JWT). Send the signed JWT as a Bearer token in the `Authorization` header.

<Steps>
  <Step title="Build the JWT header">
    Use the `HS256` algorithm.

    ```json theme={null}
    {
      "alg": "HS256",
      "typ": "JWT"
    }
    ```
  </Step>

  <Step title="Build the JWT payload">
    Set `iss` to your API Secret ID and `iat` to the current Unix timestamp in seconds.

    ```json theme={null}
    {
      "iss": "YOUR_API_SECRET_ID",
      "iat": 1713225600
    }
    ```
  </Step>

  <Step title="Construct the signing secret">
    Concatenate your API Secret ID and API Secret Key with `||` between them.

    ```text theme={null}
    YOUR_API_SECRET_ID||YOUR_API_SECRET_KEY
    ```
  </Step>

  <Step title="Sign and send the JWT">
    Sign the JWT with HMAC-SHA256 using the combined secret. Pass the resulting JWT as a Bearer token.

    ```bash theme={null}
    curl https://api.heymarket.com/v1/inboxes \
      -H "Authorization: Bearer YOUR_SIGNED_JWT"
    ```
  </Step>
</Steps>

Tokens expire 5 minutes after the `iat` timestamp. Generate a new JWT per request, or cache it briefly for less than 5 minutes.

## Python example

This example uses only the Python standard library.

```python theme={null}
import base64
import hashlib
import hmac
import json
import time

SECRET_ID = "YOUR_API_SECRET_ID"
SECRET_KEY = "YOUR_API_SECRET_KEY"


def b64(data):
    return base64.urlsafe_b64encode(data).rstrip(b"=")


header = b64(json.dumps({"alg": "HS256", "typ": "JWT"}, separators=(",", ":")).encode())
payload = b64(json.dumps({"iss": SECRET_ID, "iat": int(time.time())}, separators=(",", ":")).encode())

signing_input = header + b"." + payload
signing_secret = f"{SECRET_ID}||{SECRET_KEY}".encode()
signature = b64(hmac.new(signing_secret, signing_input, hashlib.sha256).digest())

print((signing_input + b"." + signature).decode())
```

## Check your credentials

Use `GET /v1/inboxes` as a low-risk check that your signed JWT works:

```bash theme={null}
curl https://api.heymarket.com/v1/inboxes \
  -H "Authorization: Bearer YOUR_SIGNED_JWT"
```

If the request succeeds, the response includes inbox IDs you can use with message-sending endpoints.

## Rotate an API Secret

The API settings page supports up to two API Secrets. Use the second slot to rotate without interrupting active traffic.

<Steps>
  <Step title="Generate a second API Secret">
    Create a new API Secret in **Settings > Integrations > API** and store the new Secret ID and Secret Key securely.
  </Step>

  <Step title="Deploy the new secret">
    Update your server-side integration to sign JWTs with the new Secret ID and Secret Key.
  </Step>

  <Step title="Verify the new secret">
    Call `GET /v1/inboxes` with a JWT signed by the new secret.
  </Step>

  <Step title="Revoke the old secret">
    After the new secret is deployed and verified, revoke the old API Secret.
  </Step>
</Steps>

## Legacy API key authentication

Existing integrations may still authenticate with a team API key while migration is planned.

```bash theme={null}
curl https://api.heymarket.com/v1/inboxes \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Warning>
  API key authentication is planned for deprecation. New integrations should use API Secret JWT authentication.
</Warning>

## Request IDs

Every API response includes an `X-Request-Id` header. Record this value when you encounter an error. Heymarket support uses it to look up the specific request.

```text theme={null}
X-Request-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
```