Admin Authentication

The Bagisto Admin REST API authenticates every request with a pre-issued Integration token. There is no login call — you generate a token once in the admin panel and send it on every request.

How to authenticate

1. In the admin panel, open the Integration menu (Admin → Integration) and generate a token.
2. Copy the token the moment it is shown — it is displayed once.
3. Send it on every Admin API request as a Bearer token:

Authorization: Bearer <id>|<token>

That single header is all that is required. The /api/admin/* routes do not use the storefront key — only the Bearer token above.

About the token

• The token belongs to a specific admin user and carries that admin's permissions. A request can never do more than the owning admin is allowed to do.
• The plaintext format is <id>|<random>. Send it verbatim.
• A token can be locked down with scoped permissions, an IP allowlist, an expiry date, and rate limits — see Token security below.
• Revoke or regenerate a token at any time from the same Integration menu. A revoked token stops working immediately.

Token security

Each Integration token can be locked down at generation time in the Integration menu. Four independent controls scope what a token can do:

Permissions (ACL)

A token is tied to one admin and inherits that admin's role permissions — it can never do more than its owner. When generating the token you choose a permission mode:

• All — every action the owner's role allows.
• Custom — a specific subset of permissions you select, frozen onto the token.
• Same as web — always mirrors the owner's current role, so the token automatically follows any later changes to that role.

A request for an action the token isn't permitted to perform returns HTTP 403 with a problem-details body:

{
  "type": "/errors/403",
  "title": "Forbidden",
  "status": 403,
  "detail": "You do not have permission to view this sales resource."
}

IP allowlist

Optionally restrict a token to specific client IPs. Individual IPv4 and IPv6 addresses and CIDR ranges are all supported. Leave the allowlist empty to allow any IP. A request from an address that isn't on the list is rejected as 401 Unauthenticated. (127.0.0.1 is always allowed, for local development.)

Expiry

A token can have an expiry date (default: one year after generation) or be set to never expire. After the expiry date the token stops working (401).

Rate limits

Each token carries two independent caps, both set when the token is generated:

Bucket	Default
Per minute	60 requests
Per day	10,000 requests

Exceeding either returns HTTP 429 with {"message": "Too Many Attempts.", "error": "rate_limit_exceeded"} and these headers:

Header	Meaning
Retry-After	Seconds until the bucket refills
X-RateLimit-Limit	The cap that was hit
X-RateLimit-Remaining	Requests left, 0 on a 429
X-RateLimit-Reset	Unix timestamp when the window resets

Three details worth knowing:

• The two caps are separate buckets. Hitting the per-minute cap does not consume the daily allowance, and the Retry-After you get back tells you which one you hit — roughly a minute versus the remainder of the day.
• The cap is per token, not per admin or per IP. Two tokens owned by the same admin have independent allowances.
• REST and GraphQL share one bucket. /api/admin/graphql draws on the same per-token allowance as the REST routes, so a client using both must budget across the two.

Choose Unlimited for either bucket when generating or editing the token to remove that cap; set both to Unlimited for an unthrottled token.

Token lifecycle

• One active token per admin. Each admin user holds a single active (or draft) token at a time. To issue a new one, revoke or regenerate the existing token first — the generate form only offers admins who don't already have one.
• States. A token moves through draft (created but not yet generated — no secret), active (generated and usable), revoked (manually killed — stops working immediately, kept for audit), and regenerated (superseded by a newer token — the old row is retired but kept for audit).
• Regenerate. Issues a fresh secret on a new token row and retires the old one; the new plaintext is shown once. Use it when a token may be compromised, without losing the audit trail.
• Revoke. Kills the token immediately — from the Integration menu, or the one-click link in the lifecycle email.
• Email notifications. The owning admin is emailed on generate, regenerate, and revoke. Generate and regenerate emails carry a signed, 7-day, login-free revoke link so the owner can kill a token from their inbox. The plaintext token is never included in any email.

Errors

Condition	HTTP	Body
Missing / malformed / expired / revoked token, or client IP not on the token's allowlist	401	{"message": "Unauthenticated.", "error": "unauthenticated"}
Token valid but lacks permission for the action	403	{"type": "/errors/403", "title": "Forbidden", "status": 403, "detail": "..."}
Resource does not exist	404	{"type": "/errors/404", "title": "Not Found", "status": 404, "detail": "..."}
Per-minute or per-day rate limit exceeded	429	{"message": "Too Many Attempts.", "error": "rate_limit_exceeded"}

Examples

Use the interactive example on the right to see an authenticated request in cURL, Node.js, React, and PHP.