Grants API

Routing grants give a program a defined set of paths it can use. An administrator creates named permissions, groups them into roles if useful, and assigns permissions or roles to a user. Issuing a token then captures that user's current patterns for a one-hour connection credential. Keeping assignment and issuance separate allows access to be prepared before a program connects and revoked after its token has been issued.

These routes require an administrator session. Grant mutations and token issuance additionally require a fresh authenticator code and a reason, and are audited. Read requests and sample inspection use the session without consuming an authenticator code. The pattern language is documented in Routing.

Inspect assignments

GET /auth/admin/grants returns permissions, roles, and assignments.

Define permissions and roles

POST /auth/admin/permission takes name and either pattern or sample plus fields. Optional users and roles receive the permission. The response includes the path pattern. An explicit pattern is checked with the same rules as a compiled one. Sample and field modes are used only when you do not send a pattern.

POST /auth/admin/permission/delete and POST /auth/admin/role/delete take name.

POST /auth/admin/role takes name and permissions and replaces that role's list.

POST /auth/admin/assign takes user, roles, and permissions and replaces that user's access.

POST /auth/admin/grant/batch takes permissions and roles when you want to store several at once. Each permission has name and either pattern or sample plus fields. Each role has name and the permission names it includes. The call stores the permission paths and replaces the roles' permission lists in a single operation. At most 32 permissions and 32 roles are accepted. Names must be unique inside the request.

Issue a routing token

POST /auth/admin/issue with user returns a one-hour routing token and its patterns. The user must be active and must already have at least one pattern. The token is the two-part form used by mesgd forge: encrypted claims, a dot, and a PKI signature. It is not a login session. The claims are authorizations, exp, grant set to true, sub, and user.

mesgd issues at most 32 patterns. On use, it keeps a pattern only when it is in the token and still assigned, directly or through a role. Removing a permission, role, or assignment takes effect on the next check. Adding one requires a new token. A disabled or deleted account matches nothing.

The token does not act as a bag of claim names. It cannot call /auth, and grant set to true does not open / or /user/*. The program's path has to be covered by a granted pattern. /room=* is not covered by /room=lobby. /room=lobby/from=ann is covered by /room=lobby.

mesgd check uses the same rule. mesgd forge still mints a claim token and does not write these patterns.

Work from a sample message

mesgd keeps one in-memory example of each shape it routes, up to 64 shapes, so the console can show you what it has seen. Text longer than 128 bytes is dropped, and at most 32 fields are kept. This is not a message archive.

GET on examine, pattern, or suggest is 405. POST on the collection or on a sample id is 405.

instructions is trimmed and capped at 2000 bytes. Empty instructions add nothing. Suggestion tries a local model, then Grok, Claude, and ChatGPT when those keys are set. mesgd still compiles the pattern itself. It does not store the model's text unchanged. The console form is described in Console.

A sample value that contains | lists alternatives, such as lobby|game|chat. The model may set an exact field to one of those alternatives. A value that is not one of them is ignored.