Token permissions

Tokens are the primary way to authenticate with the API. They can be given permissions to access specific resources.

When you send a request to the API, you should include a token value in the x-api-token header.

We can optionally restrict tokens by a list of IP addresses. This means the token will only work when the request is made from one of the specified IP addresses.

Tokens can also be given an expiry date.

Permissions

Each token can have a list of permissions. These permissions will be evaluated in the order in which they're defined, with later permissions potentially overriding or modifying earlier ones.

Each permission has the following structure:

Allow everything
Manage items
View list events
Access owned items

[0: {mode: "allow"
action: "*"
}
]

required
mode'allow' | 'block'Whether this permission is allowing or blocking something.
required
action | '*' | 'create' | 'view' | 'update' | 'delete' | 'register' | 'authenticate' | 'reset-password' | 'verify-email' | 'create-with-identity' | 'view-with-identity' | 'update-with-identity' | 'delete-with-identity' | 'restore' | 'restore-with-identity' | 'sync-schema'
The action covered by this permission. The value '*' refers to "all actions".
The register and authenticate actions allow users to register and authenticate identities, respectively. authenticate also allows confirming a password reset or email verification with a token.
The reset-password and verify-email actions allow a token to request password reset and email verification tokens for identities in the listed groups. Unless the group delivers tokens to a webhook, the token is returned to the caller, so anyone holding an API token with these permissions could take over any identity in those groups. Only give these permissions to a token that never leaves your server. The same applies to a token that allows everything ('*').
The restore action only applies to items, and allows users to restore an item to a previous version, or restore an item that has been deleted.
The sync-schema action allows a token to create, update and prune lists and indexes from a schema document with POST /sync-schema, and to move lists between scopes. It doesn't have a resourceType or any ids. Each change a sync makes also needs the permission the equivalent request would need, e.g. create for lists, or delete for a list a prune deletes, so a token can't use a sync to change a list it isn't otherwise allowed to change. The '*' action includes it.
The create-with-identity, view-with-identity, update-with-identity, delete-with-identity, and restore-with-identity actions allow users to perform the specified action on items, but only if they're authenticated using an identity. In this case, any items they create will be associated with the identity, and any items being viewed, updated, deleted, or restored must belong to the identity.
A list whose write rules declare shared is the exception: on that list, update-with-identity and delete-with-identity let an identity write items it doesn't own, and the rules decide who may. The permission is still needed — shared only lifts the ownership check, it doesn't grant anything.
The view-with-identity action can also be used with the 'event' and 'stats' resource types, which allow users authenticated using an identity to view the event history and stats of items that belong to the identity. When using an identity, view events and stats permissions do not apply to items.
resourceType'list' | 'item' | 'index' | 'identity' | 'event' | 'stats'The type of resource this permission applies to. The values 'event' and 'stats' are only applicable when the action is 'view', and refer to the ability to view events and stats, respectively. Item events and stats can also be viewed with the 'view-with-identity' action.
listIdsstring[]
An array of list ids. This attribute can be omitted if the permission does not apply to a particular list, for example if the action is 'create' and the resourceType is 'list' (which means the permission allows lists to be created).
Additionally, the array can contain the value '*', which means the permission applies to all lists.
itemIdsstring[]
An array of item ids. This attribute can be omitted if the permission is not applicable to items.
Additionally, the array can contain the value '*', which means the permission applies to all items.
indexIdsstring[]
An array of index ids. This attribute can be omitted if the permission is not applicable to indexes.
Additionally, the array can contain the value '*', which means the permission applies to all indexes.
identityIdsstring[]
An array of identity ids. This attribute can be omitted if the permission is not applicable to identities.
Additionally, the array can contain the value '*', which means the permission applies to all identities.
groupsstring[]
An array of group names. This attribute can be omitted if the permission is not applicable to groups.
Additionally, the array can contain the value '*', which means the permission applies to all groups.
This allows you to restrict the identities that can register and authenticate when using a particular token.

Tokens in public pages

A token sent from a browser is visible to anyone who looks, so treat it as public and give it only the permissions that page actually needs. Permissions control who can read and write, and identities narrow that down to a single person's own items, but a token that can read an item can read all of it.

To hide a field from a public token while still letting it be written, use a guard index. The value at a guard index's pointer is removed from item data in every token-auth response - including event snapshots, item version history and realtime messages - so a form in a public page can collect an email address that nobody reading the list can see.

Guards apply to token auth only. Anything you put in a list is always visible to you in the jsonpad dashboard.

2026-09-12