Skip to main content
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 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.
The Secret Key is shown only when it is generated. Copy and store it securely before closing the dialog.
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.

​
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.
1

Build the JWT header

Use the HS256 algorithm.
{
  "alg": "HS256",
  "typ": "JWT"
}
2

Build the JWT payload

Set iss to your API Secret ID and iat to the current Unix timestamp in seconds.
{
  "iss": "YOUR_API_SECRET_ID",
  "iat": 1713225600
}
3

Construct the signing secret

Concatenate your API Secret ID and API Secret Key with || between them.
YOUR_API_SECRET_ID||YOUR_API_SECRET_KEY
4

Sign and send the JWT

Sign the JWT with HMAC-SHA256 using the combined secret. Pass the resulting JWT as a Bearer token.
curl https://api.heymarket.com/v1/inboxes \
  -H "Authorization: Bearer YOUR_SIGNED_JWT"
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. 
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: 
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.
1

Generate a second API Secret

Create a new API Secret in Settings > Integrations > API and store the new Secret ID and Secret Key securely.
2

Deploy the new secret

Update your server-side integration to sign JWTs with the new Secret ID and Secret Key.
3

Verify the new secret

Call GET /v1/inboxes with a JWT signed by the new secret.
4

Revoke the old secret

After the new secret is deployed and verified, revoke the old API Secret.

​
Legacy API key authentication

Existing integrations may still authenticate with a team API key while migration is planned. 
curl https://api.heymarket.com/v1/inboxes \
  -H "Authorization: Bearer YOUR_API_KEY"
API key authentication is planned for deprecation. New integrations should use API Secret JWT authentication.

​
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. 
X-Request-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890