Skip to content
This page View Markdown Open in ChatGPT Open in Claude

API user permissions

An API user is an application : the web app, the mobile app, a partner. It signs in with a username and a password, gets a token, and every call carries that token in x-am-authorization. Its groups decide which APIs the application can call at all.

In short

  • An API user is one app : a username, and a password kept in the secret.
  • The app gets a token with them, and sends it on every call in x-am-authorization.
  • Its groups say what it may call.
A new API user : its name, username and the path of its password in the secret
  1. A name : the app that will call.
  2. Its username.
  3. Where its password is kept in the secret.
  4. Save User.
Page Security → API User Permissions : the API users on the left, the groups of the selected one on the right.
Fields Name, username and Password Path : the key of your default secret which holds the password (common.apiUserPasswords.default).
Token POST /api/system-api/<user path>/token with { "u": "username", "p": "password" }.
Swagger Enable Swagger Docs and a Swagger Token publish the documentation of the APIs this API user can call : View Swagger JSON opens it.
New account An API user default, with the group Default. Its password is read from the secret, at common.apiUserPasswords.default : empty until you type one.

Set one up

  1. Add New, give the name and the username.
  2. Select the Password Path. The password lives in the secret of each environment, not in API Maker's data and not in Git. Open Secret adds a new key.
  3. Check the groups it gets. An API user with several groups can call what any of them grants.
  4. Save User. The application gets its token with the username and the password.

Swagger docs per API user

  • Generate a random Swagger token and enable the docs : the URL shown answers with the OpenAPI document of exactly the APIs this API user can call, database, custom and system APIs alike.
  • Share it with the team which builds on that API user. Disable the docs, or generate a new token, to stop an old URL.

Good to know

  • Changing the password invalidates the tokens made before : the value in the secret, or the Password Path itself.
  • API users go to Git ; their password does not.
  • The API of the panel takes apiUserPasswordPath too : a new API user has to name it, and a request with password is refused.
  • An API user made before version 4.1.0 with a typed password keeps it and keeps signing in. Editing it asks for a Password Path, which replaces the old password for good.