Sending the token
Send it on every request, in either form:
Authorization: Bearer djc_…
# or, equivalently
X-API-Key: djc_…A missing, revoked or expired token returns 401. Tokens always start with djc_. There are no unauthenticated routes.
Scopes: read vs read & write
When you create a token you pick one access level, applied to every resource you tick:
| Level | What it allows |
|---|---|
| Read only | Every GET, plus the two body-carrying reads on Knowledge: POST …/search and POST …/ask. Nothing is created, changed, deleted or run. |
| Read & write | Everything: create bases and flows, add / edit / delete entries, submit material, import, edit nodes and edges, test a node, run a flow. Write includes read. |
Internally a scope is written <resource>:<level> — knowledge:read, workflows:write — and that is what /me reports back.
Per-resource access
Each resource is a checkbox on the token page, so one token can hold different levels for different things — for exampleKnowledge · read & write and Workflows · read for an agent that maintains your FAQ but should only everinspect your automations. Calls to a resource the token was not given at all return the same 403 as an insufficient level.
| Resource | Base URL | Read covers | Write adds |
|---|---|---|---|
| Knowledge | https://api.simplynice.ai/api/ai/knowledge | list bases, read entries, search, ask, export, gaps | create bases, add/edit/delete entries, import, submissions, uploads, bulk actions |
| Workflows | https://api.simplynice.ai/api/ai/simple-flow | list flows, graphs, nodes, edges, executions, node catalog | create flows, edit graph/nodes/edges, test a node, execute |
Expiry, revocation, reveal
- Expiry is optional (never, 30 days, 90 days, 1 year). An expired token answers
401and shows as Expired on the token page. - Revoke from the token page; the token stops working on the next request. Revoking cannot be undone — create a new token instead.
- Reveal shows the full token again on the token page, so you do not need to rotate it just because you lost the clipboard. Treat the page as sensitive.
- Rename freely; the name is for you.
- Up to 25 active tokens per person per workspace.
Older per-item keys
If you were given a key starting kbk_ or sfk_ before personal tokens existed, it still works — but only for the single knowledge base or flow it was created for, and it cannot list or create. They are listed under Legacy keys on the token page, where you can revoke them. New integrations should use a djc_ token.
What a rejected call looks like
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"success": false,
"error": "This token has knowledge:read — POST /api/ai/knowledge/bases/…/entries needs knowledge:write",
"code": "INSUFFICIENT_SCOPE",
"details": { "required": "knowledge:write", "scopes": ["knowledge:read", "workflows:read"] }
}details.required names the scope the call needs — useful for agents, which can tell the user exactly which box to tick. SeeErrors for every code.
Hygiene
- One token per integration, named after it, so revoking one thing never breaks another.
- Read only unless the integration genuinely writes. Add write later if it turns out to be needed.
- Set an expiry for anything experimental; revoke on the day a project ends.
- Keep tokens in environment variables or a secrets manager — never in a repository, a spreadsheet or a chat.