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.
| Page | API Security → API User Permissions : the API users on the left, the groups of the selected one on the right. |
| Fields | Name, username, password, or Enable Password From Secret Path with the path of the password in the secret (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, password 12345 from the secret, with the group Default. |
Set one up¶
- Add New, give the name and the username.
- Type a password, or enable the password from a secret path : the password then lives in the secret of each environment, not in Git.
- Check the groups it gets. An API user with several groups can call what any of them grants.
- 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.
- API users go to Git ; with a password from a secret path, the password does not.