Reference

Everything Tokening 0.1 understands, on one page. The full manuals live in the repository docs.

The four parts

Part	What it is	Who holds it
Target	An API Tokening can reach: an MCP server over HTTP, or a REST base URL, plus its real credential	Operator, in the policy file and the encrypted vault
Template	A permission shape: one tool (or one HTTP method and path), the arguments allowed, their limits, the most uses and the longest lifetime	Operator, in the policy file
Grant	A template filled in for one task: the post ID, the number of uses, the deadline, who it’s for and why	Agent holds the secret; Tokening holds the record
Decision	The result of every call: allowed or refused, a code, a reason, the grant	Audit log, exportable as JSONL

Issuing a grant can only narrow a template. A text-edit template can never become a delete.

Argument rules

Rule	Works on	Meaning
`bind: required`	any value	Fixed when the grant is issued. Every call must send exactly that value.
`bind: optional`	any value	May be fixed at issue time. If it isn’t, any value of the right type is fine.
`type`	any value	`string`, `integer`, `number` or `boolean`
`enum`	strings, numbers	Must be one of a listed set
`max_len`	strings	Most characters allowed
`max_bytes`	strings	Most UTF-8 bytes allowed
`min`, `max`	numbers	Allowed range
`pattern`	strings	Must match this regular expression, start to end
`sha256`	strings	Must hash to a value bound at issue time, for approving exact text
`additional_args`	template	`refuse` (the default) refuses any field the template doesn’t name

REST templates use method and path instead of tool, for example PATCH and /records/{id}. A {name} in the path is bound like an argument. Nested objects and arrays are not supported in 0.1.

Refusal codes

Every refused call gets one of these codes and a reason written for a person. Reasons never repeat string values, because they can hold private text.

Code	Example reason
`grant_unknown`	No grant matches this token.
`grant_expired`	Grant g_61c5… expired at 2026-10-26T10:14:00Z.
`grant_exhausted`	Grant g_61c5… allowed 1 use and has none left.
`grant_revoked`	Grant g_61c5… was revoked at 2026-10-26T10:05:00Z.
`tool_not_allowed`	Grant allows wp_update_post; call asked for wp_delete_post.
`arg_mismatch`	Grant is bound to id 2; call sent id 3.
`arg_not_allowed`	Grant does not allow argument status. Allowed: content, id, title.
`arg_limit`	Argument title is 240 characters; grant allows up to 200.

When an allowed call fails at the API, the log adds an upstream_error record linked to the allowed one. The use stays spent.

Agent endpoints

The agent port defaults to 127.0.0.1:8080. Every request carries Authorization: Bearer <grant secret>.

Endpoint	Use
`POST /mcp/{target}`	MCP over HTTP. `tools/list` shows only the tool the grant allows. `tools/call` is checked, spent and forwarded.
`ANY /http/{target}/{path}`	REST passthrough for REST targets
`GET /grant`	What this grant allows, in plain English and JSON. Doesn’t spend a use.

Operator commands

The admin port defaults to 127.0.0.1:8081 and needs TOKENING_ADMIN_TOKEN. Keep it away from agents.

Command	Does
`tokening serve`	Start both ports
`tokening check <policy>`	Validate a policy file
`tokening target add <name> --cred-file <file>`	Store a real credential in the vault
`tokening template list`	Show the loaded templates
`tokening grant issue <template> ...`	Issue a grant and print its secret once
`tokening grant inspect <id>`	Uses left, expiry and every decision
`tokening grant revoke <id> --by <name>`	Stop a grant now
`tokening log --follow`	Watch decisions live
`tokening log --export`	Export the audit log as JSONL
`tokening doctor`	Look for credential variables in the agent’s environment
`tokening keygen`	Make a random vault key or admin token

A read-only panel is at /admin/panel on the admin port.

Not in 0.1

Stdio MCP servers, grant requests that wait for human approval, nested argument rules, rate limits, key rotation and a hosted service. Tokening checks permissions. It doesn’t judge whether the words an agent writes are any good, and it can’t narrow an API key that’s used outside the gateway.

Details: policy, matcher, MCP adapter, REST gateway, server, audit log.