Authentication & Access
API applications & keys
Configure system.App integrations, generated JQL tokens, namespace directives, and scoped filters.
API applications are tenant-scoped server-to-server clients. Creating a system.App generates a linked JqlToken; your service sends that token with authenticationClass: "api_key".
Keep JQL tokens on the server. Browser embeds should use public surfaces or authenticated user sessions, not API application keys.
Grant access with namespace configurations
An app is useful only after it has namespace configurations. Each configuration defines:
namespace: the resource family being configured.directive: the schema, namespace, and action pattern.filter: JSON added as an allow boundary.exclude: JSON added as a deny boundary.
Directive examples:
model:objects.Record:retrieve
model:objects.Record:create
model:tasks.Task:*
controller:billing.Invoice:create_payment_link
*:assets.Asset:*Prefer exact directives. Wildcards are available for platform apps, but broad grants make token rotation and incident response harder.
Example app-scoped retrieve
1{
2 "__meta__": {
3 "schema": "model",
4 "namespace": "objects.Record",
5 "intent": "retrieve",
6 "authenticationClass": "api_key",
7 "return": {
8 "id": null,
9 "data": null,
10 "modified": null
11 }
12 },
13 "filter": {
14 "object__namespace": "Invoice"
15 }
16}If the app configuration contains a filter such as:
{
"object__namespace": "Invoice",
"data__status": "approved"
}then the token can only see the approved invoice records even if the request tries to ask for more.
Token behavior
Generated tokens use the jql:k... format and are persisted as JqlToken rows. Tokens may be persistent or expiring, and validation updates last_used. Ephemeral tokens are deactivated after validation.
Rotate a token by creating a replacement application key, deploying the new secret, and disabling the old token after traffic has moved.
For the JQL request contract, read /reference/jql-overview. For namespace naming and dynamic object namespaces, read /reference/namespaces.