Authentication

The Brandmachine API supports several authentication methods. For programmatic (machine-to-machine) access, generate a Bearer API token from your dashboard.

Authentication Methods

Brandmachine accepts:

  1. API tokens (Bearer, prefix bm_), primary path for server-to-server and CLI integrations.
  2. Shopify JWT: used by the Shopify-embedded app automatically.
  3. Auth0 JWT: used by the direct (non-Shopify) web app for self-signup teams.

This guide focuses on API tokens. The JWT paths are handled by the app frontends and aren't intended for direct use.

Getting Your API Token

  1. Log into your Brandmachine dashboard.
  2. Navigate to Settings → API.
  3. Click Generate New API Token.
  4. Copy and securely store your token. It starts with bm_.

Important: Your API token is shown only once. Store it securely; if you lose it, you'll need to generate a new one.

Making Authenticated Requests

Include your API token in the Authorization header of every request:

Authorization: Bearer bm_your_token_here

Using cURL

curl -X POST https://production.api.brandmachine.shop/graphql \
  -H "Authorization: Bearer bm_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ getShopName }"
  }'

Using JavaScript (fetch)

const response = await fetch('https://production.api.brandmachine.shop/graphql', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer bm_your_token_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: `
      query {
        getShopName
      }
    `,
  }),
});

const data = await response.json();

Using Python (requests)

import requests

url = 'https://production.api.brandmachine.shop/graphql'
headers = {
    'Authorization': 'Bearer bm_your_token_here',
    'Content-Type': 'application/json',
}
query = '''
  query {
    getShopName
  }
'''

response = requests.post(url, json={'query': query}, headers=headers)
data = response.json()

Token Management

Rotating Tokens

For security, rotate your API tokens periodically:

  1. Generate a new token in the dashboard.
  2. Update your applications with the new token.
  3. Test that the new token works.
  4. Revoke the old token.

Revoking Tokens

If a token is compromised:

  1. Navigate to Settings → API.
  2. Find the token in your active tokens list.
  3. Click Revoke.
  4. Generate a new token immediately.

Security Best Practices

Never Commit Tokens to Version Control

Always store tokens in environment variables or a secrets manager:

# .env file (add to .gitignore)
BRANDMACHINE_API_TOKEN=bm_your_token_here

const token = process.env.BRANDMACHINE_API_TOKEN;

Use Environment-Specific Tokens

Issue separate tokens for development, staging, and production. That way you can rotate or revoke a single environment without breaking the others.

Monitor Token Usage

Review token usage in the dashboard at Settings → API → Activity. Investigate any unexpected patterns.

Troubleshooting

Error: "Not authenticated"

Cause: Missing or malformed Authorization header.

Solution: Make sure the header is exactly:

Authorization: Bearer bm_your_token_here

Note the space between Bearer and the token.

Error: "Invalid token"

Cause: Token is expired, revoked, or incorrect.

Solution:

  1. Verify the token is copied correctly (no extra whitespace).
  2. Check whether the token was revoked.
  3. Generate a new token if needed.

Error: "Forbidden"

Cause: Token is valid but lacks permission for this operation.

Solution:

  1. Check the token's scope in the dashboard.
  2. Generate a new token with appropriate permissions if needed.

Next Steps