# Secure Your APIs

> Decide which app may call which API of API Maker - make a group of allowed APIs, an API user for each app, give it its groups, check a refused and an allowed call, choose public or private access, and let the security report check the whole account.

Source: https://docs.apimaker.dev/v4/docs/getting-started/secure-your-api.html

Every API of API Maker is locked : a call without a valid token gets `401`. You decide who gets a token, and what each token may call. You write no code for it.

> **In short**
>
> - A **group** is a list of what may be called : APIs, tables, fields.
> - An **API user** is one app : a username and a password. Give it one or more groups.
> - The app trades its username and password for a **token**, and sends the token on every call.
> - The **security report** reads the whole account and says what to fix.

> 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.

- Video: [API Authorization Without Auth Code: Access Types, API Users, Groups](https://apimaker.dev/videos/authorization-basics) (6 min)

## 1. Make a group

Open **Security → API Group Permissions** and press **+**. Name the group after what it is for, for example `Support team`, then press **Save Group**.

Pick the group, then go from left to right : the kind of API, the instance, the database, the table.

[![API Group Permissions : from left to right, the group, the kind of API, the instance and database, then the tables](https://docs.apimaker.dev/assets/images/screens/sec-group.webp)](https://docs.apimaker.dev/assets/images/screens/sec-group.webp)

1. The groups. Pick one.
2. The kind of API : the APIs of your tables, custom APIs, system APIs.
3. The instance, then the database.
4. The tables. Then tick the APIs of each table it may call.

Tick the APIs of each table the group may call : for example **Get all** and **Get by id** to read, and nothing to write. The **Schema Fields** column limits the fields it may read and write. Press **Save**.

## 2. Make an API user

Open **Security → API User Permissions** and press **+**. One API user is one app : your website, your mobile app, a partner.

[![A new API user : its name, username and the path of its password in the secret](https://docs.apimaker.dev/assets/images/screens/sec-api-user.webp)](https://docs.apimaker.dev/assets/images/screens/sec-api-user.webp)

1. A name : the app that will call.
2. Its username.
3. Where its password is kept in the secret.
4. **Save User**.

The password is not typed here. It stays in your **default secret**, encrypted, and **Password Path** names its key. Open **Security → Secret Management** and add it :

```typescript
apiUserPasswords: {
    default: 'Choose_A_Password_1',
    support_desk: 'a-long-password-for-the-support-desk',   // the new API user
},
```

## 3. Give it its groups

Back on **API User Permissions**, pick the API user, tick its groups, and press **Save**.

[![API User Permissions : an API user on the left, the groups it belongs to on the right](https://docs.apimaker.dev/assets/images/screens/sec-user-groups.webp)](https://docs.apimaker.dev/assets/images/screens/sec-user-groups.webp)

1. The API user. Pick it.
2. Tick the groups it belongs to.
3. **Save**.

## 4. Try it

In **API Testing**, the **Header** tab has the row `x-am-authorization` : pick your new API user there. Call an API its groups do not allow :

[![A call refused with 403 : no group of the API user allows this API](https://docs.apimaker.dev/assets/images/screens/sec-refused.webp)](https://docs.apimaker.dev/assets/images/screens/sec-refused.webp)

1. `403` : no group of this API user allows the call.
2. The reason.

`403` : refused, with the reason. Call an API the group allows, and the data comes back. Your app does the same with a token :

```bash
# 1. the token of the API user
curl -s -X POST "$AM/api/system-api/admin/token" \
  -H "Content-Type: application/json" \
  -d '{ "u": "support_desk", "p": "a-long-password-for-the-support-desk" }'

# 2. a call, with the token
curl -s "$AM/api/schema/admin/mongodb/shop/customers" -H "x-am-authorization: <the token>"
```

## 5. Public, private, or only for your code

Each table and each custom API has an **access type** :

| Access type | Who may call |
|---|---|
| `TOKEN_ACCESS` | Only callers with a token whose groups allow it. The default. |
| `IS_PUBLIC` | Anyone, without a token : a public price list, a contact form. |
| `NO_ACCESS` | Nobody from outside : only your own code and API Testing. |

Set it in the [settings of the table](https://docs.apimaker.dev/v4/docs/settings/collectionSettings.html) or of the [custom API](https://docs.apimaker.dev/v4/docs/settings/customApiSettings.html).

## 6. Let the security report check the account

Open **Security → APIs Security Report & Actions**. It reads every setting, group, hook and line of code of the account, and gives a score out of 100.

[![APIs Security Report and Actions : a score of 95 out of 100, and where the risks are](https://docs.apimaker.dev/assets/images/screens/sec-report.webp)](https://docs.apimaker.dev/assets/images/screens/sec-report.webp)

1. **Scan** the account again after a change.
2. The score, out of 100.
3. Where the risks are. Open one to see the finding and its fix.

Each finding says what a person could reach, with the request that proves it. Most have a fix : look at the change, apply it, and the account is scanned again.

- Video: [APIs Security Report: Find Data Leaks and Fix Them in One Click](https://apimaker.dev/videos/security-report) (11 min)

## People, not only apps

An API user is an app. When people sign in to your app, each person can also get a token, and a pre hook keeps them to their own rows : see [the two gates](https://docs.apimaker.dev/v4/docs/getting-started/how-it-works.html#the-two-gates) and [Handle role based permissions](https://docs.apimaker.dev/v4/docs/authorization/handle-role-based-permissions.html).

Before real users arrive, go through [Before you go live](https://docs.apimaker.dev/v4/docs/security/go-live.html) : the default API user and its group `Default`, which allows everything, must go.