Developer Documentation

API Tokens

Self-service, shop-scoped tokens for calling the Legion API from your own backend — starting with enabling and disabling user accounts.

1. Generate

A shop Owner or Admin creates a token in the admin dashboard under Settings → API Tokens. It is revealed exactly once.

2. Call the API

Your backend sends the token as a bearer token. Every request is scoped to your own shop — no other tenant is reachable.

3. Revoke anytime

Revoke a token from the same settings page. It stops working on the very next request.

Self-Service

Shop-Scoped

Revocable

API Tokens (Self-Service)

API tokens let your backend call the Legion API directly — no widgets, no user session — to automate account administration for your own tenant. The first supported use case is enabling and disabling user accounts (the active flag), for example after verifying a customer in your ERP or CRM.

Tokens are generated by you, from the Legion admin dashboard. No contact with Legion support is required.

Who can generate tokens

Any dashboard user with the Owner or Admin role on your shop. Tokens are always scoped to the shop they were generated in: a token can only read or modify users that belong to your own tenant. Requests against any other tenant's data return 404 Not Found.

Generating a token

Log in to the Legion admin dashboard.
Go to Settings → API Tokens.
Click Generate Token.
Give the token a descriptive name (e.g. ERP customer sync) and pick an expiration: 30, 90, or 365 days.
Click Generate.

The token is shown exactly once, in the "API Token Created" dialog. Copy it and store it in your secret manager immediately — Legion does not store the token and cannot show it again. If you lose it, revoke it and generate a new one.

Using a token

Send the token as a standard bearer token in the Authorization header:

Authorization: Bearer <YOUR_API_TOKEN>

Enable or disable a user account

PATCH /api/user/profile flips a user's active flag. Identify the target user with exactly one of id, email, phone, or username. Pass active: true or active: false explicitly, or omit active to toggle the current value.

# Disable a user by email
curl -X PATCH "https://your-legion-domain.com/api/user/profile" \
  -H "Authorization: Bearer $LEGION_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "email": "[email protected]", "active": false } }'

# Re-enable a user by id
curl -X PATCH "https://your-legion-domain.com/api/user/profile" \
  -H "Authorization: Bearer $LEGION_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "id": "9a1f...c3", "active": true } }'

A successful response returns the user's new state:

{
  "id": "9a1f...c3",
  "active": true,
  "email": "[email protected]",
  "phone": "+15551234567",
  "username": "customer1"
}

Node.js example:

const res = await fetch("https://your-legion-domain.com/api/user/profile", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.LEGION_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    data: { email: "[email protected]", active: false },
  }),
});

if (!res.ok) {
  throw new Error(`Legion API error: ${res.status}`);
}
const user = await res.json();
console.log(`User ${user.id} active: ${user.active}`);

While a user is disabled, the Legion UI informs them that their access is pending approval. Accounts can also be re-activated automatically by your ERP sync, if configured.

Check whether a customer exists

GET /api/admin/users/exists looks up a customer by exactly one of email or phone within your shop.

curl "https://your-legion-domain.com/api/admin/users/[email protected]" \
  -H "Authorization: Bearer $LEGION_API_TOKEN"

{
  "exists": true,
  "user": { "id": "9a1f...c3", "email": "[email protected]", "phone": null },
  "matchCount": 1
}

When no customer matches, the response is { "exists": false, "user": null, "matchCount": 0 }.

Create a customer

POST /api/admin/users creates a customer in your shop. At least one of email or phone is required; firstName and lastName are optional. The call is idempotent — if a customer with the same email or phone already exists, they are returned with created: false (status 200) instead of a duplicate being created (status 201).

curl -X POST "https://your-legion-domain.com/api/admin/users" \
  -H "Authorization: Bearer $LEGION_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "firstName": "Ada", "lastName": "Lovelace" }'

{ "created": true, "user": { "id": "9a1f...c3" } }

Phone numbers are normalized to E.164 before matching or storing, so 555-123-4567 and +15551234567 refer to the same customer.

Response codes for the customer endpoints:

Status	Meaning
`200`	Lookup succeeded (`exists` may be `true` or `false`), or the customer already existed (`created: false`).
`201`	The customer was created (`created: true`).
`400`	Missing/ambiguous identifier or invalid phone number.
`401`	Missing, malformed, expired, or revoked token.
`409`	The email and phone belong to two different existing customers.

Response codes for `PATCH /api/user/profile`

Status	Meaning
`200`	The `active` flag was updated; the response body contains the new state.
`400`	Missing or ambiguous identifier, or `active` was not a boolean.
`401`	Missing or malformed `Authorization` header, or the token has expired.
`403`	The token was revoked, or is not valid for this operation.
`404`	No user matched the identifier within your shop.

Revoking a token

Tokens can be revoked at any time from Settings → API Tokens — click Revoke next to the token. Revocation takes effect immediately: the next request made with that token is rejected with 403. Revoke a token right away if it may have been exposed, and generate a replacement.

Security best practices

Server-side only. API tokens carry admin-level privileges for your shop. Never embed them in a browser, mobile app, or widget. For user-facing widgets, use SSO authentication instead — those tokens are short-lived and scoped to a single end user.
Store tokens in a secret manager (environment variables, Vault, etc.), never in source control.
One token per integration. Give each system (ERP sync, support tooling, etc.) its own named token so you can revoke one without breaking the others.
Prefer shorter expirations and rotate: generate a new token, deploy it, then revoke the old one.

Full API reference

The interactive API reference at /api/docs lists every endpoint available to your integration, with request and response schemas. Endpoints tagged with bearer authentication accept either an API token (shop-scoped, admin operations) or an end-user token (SSO / widget flows), as noted per endpoint.