# API User Permissions

> An API user is the identity of an application which calls API Maker - its token goes in x-am-authorization, its groups decide the APIs reachable, its password can live in the secret, and it can publish Swagger docs of its APIs.

Source: https://docs.apimaker.dev/v1/docs/apis-security/api-user-permission.html

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](https://docs.apimaker.dev/v1/docs/secrets/secrets.html) (`common.apiUserPasswords.default`). |
| Token | [`POST /api/system-api/<user path>/token`](https://docs.apimaker.dev/v1/docs/apis-all/system-apis/system-generated-token-api.html) 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

1. **Add New**, give the name and the username.
2. Type a password, or enable the password from a secret path : the password then lives in the secret of each environment, not in Git.
3. Check the [groups](https://docs.apimaker.dev/v1/docs/apis-security/api-group-permission.html) 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.
- API users go to Git ; with a password from a secret path, the password does not.

## Related

- [Get token API](https://docs.apimaker.dev/v1/docs/apis-all/system-apis/system-generated-token-api.html) · [API group permissions](https://docs.apimaker.dev/v1/docs/apis-security/api-group-permission.html) · [Auth of API user](https://docs.apimaker.dev/v1/docs/authorization/AMApiUser.html)