# API Group Permissions

> Groups are the permission unit of API Maker - which tables, APIs and fields, which custom, system and third party APIs, which WebSocket events - given to API users and named in the groups column of your own users.

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

A group is a list of what may be called : tables and their APIs, fields readable and writable, custom APIs, system APIs, third party APIs, WebSocket events. An [API user](https://docs.apimaker.dev/v1/docs/apis-security/api-user-permission.html) gets groups ; a person of your users table gets groups through the `groupsColumn` of its [auth provider](https://docs.apimaker.dev/v1/docs/authorization/AMDB.html). A call passes when the API user grants it and, when a person is involved, the person too.

> Diagram : Two tokens, two gates : the API user (which application) and the person (which rows)
>
> Two identities on every request : the API user token from the token API in x-am-authorization tells which application calls, and the token of a person from a token generator in x-am-user-authorization tells who the person is. Groups of the API user decide which APIs, tables and fields may be called ; pre hooks decide which rows belong to the person.

| | |
|---|---|
| Page | `API Security → API Group Permissions` : the groups on the left, the tree of the account on the right. |
| Grants | Instances → databases → tables → APIs, and the fields of a table with **R** and **W** ; custom APIs ; system APIs ; third party APIs ; WebSocket events. |
| Shortcuts | **All APIs**, **All Fields**, **All Third Party APIs** and the checkbox of a column check everything below it. New tables and APIs are covered by an "all" grant. |
| Refused with | `403` when no group of the caller grants the API ; a field not readable is absent from the answer, a field not writable is refused on save. |

## Make a group

1. **Add New**, give a unique name, **Save Group**. **Clone** copies an existing group.
2. Open the tree. Each API shows how it is reachable, from its settings : **Public**, **AM-User** (API user token), **DB-User** (person token), **Google**, **Azure**, or **No-Access**.
3. Check the APIs and, under a table, the fields : **R** to read them, **W** to write them.
4. **Save group settings**. **Active API users in this group** shows who has it.

## Give it

- To an API user : the groups list on the [API User Permissions](https://docs.apimaker.dev/v1/docs/apis-security/api-user-permission.html) page.
- To a person : write the group names, comma separated, in the column named by `groupsColumn` of the auth provider. `*` gives the person every group of the API user.

## Good to know

- The pre and post hooks of an API can be limited to some groups : they run only for callers of those groups.
- The [APIs Security Report](https://docs.apimaker.dev/v1/docs/apis-security/api-security-report.html) lists the groups which reach too far.
- Groups go to Git : the same permissions on every environment.

## Related

- [Handle role based permissions](https://docs.apimaker.dev/v1/docs/authorization/handle-role-based-permissions.html) · [API user permissions](https://docs.apimaker.dev/v1/docs/apis-security/api-user-permission.html) · [Auth of database user](https://docs.apimaker.dev/v1/docs/authorization/AMDB.html)