Developers
Access tokens
Create, scope, and revoke the tokens the API and MCP server accept.
Access tokens let software and AI agents work on your agency: the REST API and the MCP server both take them. Only the agency owner can create or revoke tokens.
A token looks like lsk_live_ followed by a long random string. Treat it like a password.
Create a token
There are two places to make one. Both create the same kind of token and list it under Issued tokens.
For the API
- Open Developers → API: app.luminasales.io/developers/api.
- Under Access tokens, fill in Create access token:
- Token name: what it is for, like "Content scheduler".
- Expires after: 7, 30, 90 (default), or 180 days, or 1 year.
- Permissions: tick what it needs (see the table below). Read the account and Read and export Blogs start ticked.
- Create it. The page shows Copy this token now.
- Press Copy token, store it somewhere safe, then press I saved it.
For an AI agent (MCP)
- Open Developers (the MCP tab): app.luminasales.io/developers.
- In 2. Token, set a Name, Expires after (30, 90, or 180 days, or 1 year), and Access:
- Full control: read and change the account, plus read, edit, and generate blogs.
- Read only: read the account and blogs, including client details and portal links.
- Press Create token. The token is filled into every setup snippet on the page.
See MCP server for the rest of the setup.
Scopes
| Permission in the dashboard | Scope | What it allows |
|---|---|---|
| Read the account | api:read | Every GET request outside Blogs |
| Change the account | api:write | Every POST, PUT, PATCH, and DELETE outside Blogs |
| Read and export Blogs | blogs:read | Read and export blog posts |
| Edit Blogs | blogs:write | Edit blog posts. Spends no credits. |
| Generate Blogs | blogs:generate | Generate a new post. Spends 1 Lumina AI credit each. |
api:read and api:write do not reach Blogs. A blog integration needs the blogs: scopes.
Give each token the smallest set it needs. A website that only shows your blog posts needs Read and export Blogs and nothing else.
A request outside the token's scopes fails with 403 insufficient_scope.
A token acts as the person who made it
Every request with a token runs as the owner who created it, inside that one agency. On every request Lumina checks that:
- the token is not expired or revoked,
- its creator is still a member of the agency,
- the creator's own permissions allow the action.
If the creator leaves the agency, their tokens stop working.
What needs the owner's approval
Some actions move money, change who has access, or cannot be undone. A token is not refused for them any more. Instead the request waits for the owner to approve it:
- inviting, re-scoping, or removing team members, and resending or revoking invites,
- opening the Stripe billing portal,
- changing notification settings,
- requesting account deletion,
- renaming your subdomain, removing a custom domain, and changing your referral code,
- resuming or cancelling billing on a build, and cancelling one live line,
- publishing a demo into an extra paid slot,
- deleting a client, deal, demo, custom niche, lander, lander video, onboarding form, or embed,
- rotating a client's portal link or an embed key,
- creating or revoking an access token,
- saving the automatic blog schedule,
- changing a lander's link,
- opening a client's stored login or key.
The request answers 403 approval_required with an approval_id and an approve_url. The owner approves it on Developers under Approvals, then the caller repeats the request with the X-Lumina-Approval-Id header (over MCP, the approval_id argument) and the same body. It runs once, and the approval expires after 24 hours. See MCP server.
What tokens can never do
Two things are refused for every token, even with approval, with 403 owner_action_required:
- switching the active agency,
- talking to Lumina Assistant.
Revoke a token
Every token you have issued is listed under Issued tokens on both Developers tabs, with its status (Active, Expired, or Revoked), scopes, expiry, and when it was last used.
Press the trash icon, then confirm: "Revoke <name>? Integrations using it will stop immediately." Revoking takes effect on the next request, including mid-session for an MCP client.
Keep tokens safe
- Server side only. Never put a token in browser JavaScript, a mobile app, or a public repository. Anyone who sees it can act on your agency.
- Never in a URL. Send it in the
Authorization: Bearerheader. Lumina does not accept tokens in query strings. - Out of git. Files like
.mcp.jsonhold the token. Add them to.gitignore. - Expire them. Pick the shortest expiry that works and make a new token when it runs out.
- One per integration. Then you can revoke one without breaking the others.
If something goes wrong
401 invalid_token,403 insufficient_scope,403 approval_required, or403 owner_action_required: API and MCP.- Only the owner sees the token form. Members see "Only the agency owner can create or revoke tokens."
Still stuck? Ask Lumina Assistant in your dashboard (⌘J on any page), or read how to get help.
