Authentication

Every request to the Brandmachine API, GraphQL and file uploads alike, needs a bearer token. For programmatic (machine-to-machine) access, generate an API token in the Brandmachine app.

Authentication Methods

Brandmachine accepts:

1. API tokens: the method for server-to-server and script integrations. This page covers them.
2. Auth0 session tokens: used by the Brandmachine web app for signed-in users.
3. Shopify session tokens: used by the Brandmachine app inside Shopify Admin.

The session tokens are handled by the apps themselves and are not meant for direct use.

About API Tokens

• An API token is a signed JSON Web Token (JWT). It is a long string that starts with eyJ. There is no fixed prefix to check for.
• Each team has one API token at a time. It acts on behalf of the whole team and sees the same data the team sees in the app.
• Tokens do not expire. A token stays valid until you regenerate or delete it.
• The full token is shown only once, when it is created. Brandmachine stores only a hash of it, so it cannot show it to you again.

Getting Your API Token

1. Sign in to Brandmachine.
2. Open Settings, find the API Access tile and click Manage API Token.
3. Click Generate API Token.
4. Copy the full token and store it somewhere safe, such as your secrets manager.

If you lose the token, regenerate it (see below). The page also shows when the token was created and when it was last used.

Making Authenticated Requests

Send the token in the Authorization header of every request:

Authorization: Bearer YOUR_API_TOKEN

Using cURL

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

Using JavaScript (fetch)

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

const data = await response.json();

Using Python (requests)

import os
import requests

url = 'https://production.api.brandmachine.shop/graphql'
headers = {
    'Authorization': f"Bearer {os.environ['BRANDMACHINE_API_TOKEN']}",
    'Content-Type': 'application/json',
}
query = '''
  query {
    currentTeam {
      teamDomain
    }
  }
'''

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

The same header works for the File Uploads endpoints.

Blocked Operations

A few operations only work inside the Brandmachine app and are refused for API tokens. They start paid generations, release results for export, move money, change shared libraries, or permanently delete work together with its released images. A call made with an API token fails with an error message like Abort.403: Operation 'startProductStudioFlow' is not available for API token authentication.

Each of these is also marked Not available with API tokens in the Queries and Mutations reference.

Token Management

Regenerating a Token

On the Manage API Token page, click Regenerate Token and confirm. This creates a new token and invalidates the old one immediately, so every application still using the old token stops working. Because a team has only one token, plan the switch:

1. Regenerate the token.
2. Copy the new token and update every application that uses it.
3. Check that the applications work with the new token.

Deleting a Token

If a token is compromised or no longer needed, click Delete Token on the same page. Requests with the deleted token fail right away. You can generate a new token at any time.

Security Best Practices

Never Commit Tokens to Version Control

Store tokens in environment variables or a secrets manager:

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

const token = process.env.BRANDMACHINE_API_TOKEN;

Keep the Token on the Server

The token gives full access to your team's data through the API. Use it from your own backend or scripts, never from code that runs in a browser or a mobile app.

Watch the Last Used Time

The Manage API Token page shows when the token was last used. If it shows use you do not expect, regenerate the token.

Troubleshooting

Authentication fails before the request reaches GraphQL. The response has HTTP status 401 and a JSON body with a reason:

{
  "error": true,
  "reason": "API token revoked or not found"
}

If authentication succeeds but an operation returns Abort.403: Operation '...' is not available for API token authentication, the operation is one of the blocked operations.

Next Steps

• Make your first API call
• Explore available queries
• Create and update data with mutations