# API keys

> The credential another system uses to read and change your platform's data through the API: creating the key, permissions, the secret and revoking.

An API key is the credential an outside system uses to get into your platform through the API. For example: your ERP reads students and creates enrollments. The key only does what its permissions allow. In **Settings > API keys** you create keys, choose what each one can do, follow their usage and revoke them. For whoever will program the integration, the technical documentation is at https://cademi.dev/api (**Documentation** button).

## The idea in one minute

Each key has these parts:

- a **name** and a **purpose**, so you can recognize the key;
- one or more **policies**, which say what the key can do and where;
- a **validity**, the date the key stops working;
- a **secret**, the code the integration uses to identify itself.

**The most important rule:** the secret appears only once, when the key is created. After that, nobody can see the secret again. If it is lost, generate another one with **Rotate secret**.

The screen has two tabs:

- **Keys**: the credentials for the current API.
- **Legacy API**: the keys for the previous API.

## The key list

The list shows, for each key:

- **Name**, with the end of the secret, so you can tell them apart;
- **Permissions**;
- **Last used**;
- **Created**;
- **Status**: **Active**, **Suspended**, **Expired** or **Revoked**.

The **Status** filter narrows the list. A key that expires within the next seven days shows the **expires** notice with the time left.

The **Cademí support** row is the key Cademí uses to handle your tickets. The article [Cademí support access](https://help.cademi.cloud/en/conta/acesso-do-suporte-da-cademi.md) explains what it does. It also shows how to allow or remove support writing and where to see what was done.

## Creating a key

1. Open **Settings > API keys**.
2. Click **Create key**.
3. Under **Identification**, fill in the **Name**. This is how the key appears in the list and in the activity.
4. If you want, fill in the **Purpose**: where and what the key is used for.
5. Under **Permissions**, choose a template in **Start from a template**. Or click **Start from scratch** to check permission by permission.
6. Under **Validity**, choose when the key **Expires**: **Never**, **30 days**, **90 days**, **1 year** or **Choose date**.
7. Click **Create key**.
8. In the **Key created** window, copy the secret.
9. Click **I already copied it**.

The screen opens the key's page. In the **Key created** window, the **Test the key** block has a ready-made command to check that the key works.

Give the key only what the integration needs. You can adjust the permissions later. For a temporary integration, prefer an expiry.

### The permission templates

| Template | What it grants |
|---|---|
| **Read only** | Reads everything, changes nothing |
| **Content management** | Products, lessons, showcases and banners |
| **Student management** | Students, enrollments, tags and progress |
| **Sales and enrollments** | Deliveries, sale events and access |
| **Settings** | Settings, emails, custom code and profile fields |
| **Full access** | Everything except administrators and keys |

## How permissions work

A policy groups permissions and says **Where it applies**:

- **Whole account**: the policy applies to the whole account.
- **Specific products**: the policy applies to the chosen products and everything inside them: modules, lessons, exams, certificates, comments and questions.

Some permissions don't belong to a product: students, deliveries, settings. If they go into a policy restricted to products, they still apply to the whole account. The screen tells you which ones.

Opened, the policy shows the permissions by area: **Students**, **Content**, **Sales**, **Support**, **Student area**, **Settings**, **Integration and data** and **Administration**. Each resource has the columns **Read**, **Create**, **Edit** and **Delete** and the **Special actions**. The **Read only**, **All** and **None** buttons set a whole area.

**Attention:** the **Administration** area carries the **Sensitive** badge. A key with these permissions can create administrators and other keys. Give these permissions only to fully trusted integrations.

Other marks on the screen:

- **Administrators only**: an API key does not grant this permission. Only an administrator grants it to another.
- **Defined by the API**: an integration set the scope of this policy. You don't edit it on this screen. It keeps applying as it is when you publish the others.

A key can have more than one policy. **Add another policy** adds one. A key without any permission identifies itself, but every call to a resource is refused. The screen warns with **This key has no permissions**.

**Without this step, nothing changes.** On the key's page, on the **Permissions** tab, a change only applies after **Publish changes**. Each publication creates a new version, which applies from the next call. **View history** shows the versions on the **Activity** tab.

## A key's page

Click the row to open the key. The page has three tabs.

**Overview** has four panels:

- **Identification**: the name and the purpose.
- **Secret**: the **Current secret** (only its end) and the **Rotate** button.
- **Usage**: **Last used** (the last call in the last 30 days), **Environment** and **Created**. The **Environment** is **Production** or **Sandbox**. The account sets the environment when the key is created.
- **Validity and limit**: **Expires** and **Calls per minute**. Empty follows the account default. A limit of its own keeps one integration from using up the others' limit.

Changes on the **Overview** apply with **Save now**, in the footer bar.

**Permissions** is the policy editor, with **Publish changes**.

**Activity** shows everything done with the key in the last 30 days, with who did it and from where: creation, edits, permission publications, rotations, suspension and revocation. The **Type** filter separates **Creation**, **Changes**, **Secret** and **Revocation**.

### Rotate, suspend, revoke

The actions are in the row menu and in the header of the key's page.

| Action | What it does | Can it be undone? |
|---|---|---|
| **Rotate secret** | Generates a new secret. In **The current secret stops working in**, choose **1 hour**, **24 hours**, **3 days** or **7 days**. Until then, both secrets work, and you switch them in the integrations without downtime. The new one appears once, in **New secret** | After the deadline, the previous secret does not come back |
| **Suspend** | The key is refused on every call, but stays registered | Yes, with **Reactivate** |
| **Revoke** | The key stops working immediately, in every integration. It can no longer be changed. The **Activity** tab remains available | No. To integrate again, create another key |
| **Remove from list** | Removes a **Revoked** or **Expired** key from the list. What it did stays recorded in the account's activity | No |

## Legacy API

The **Legacy API** tab holds what belongs to the previous API:

- **Identification token**: the code that identifies your platform when an integration asks for it.
- **Previous API keys**: the old keys, with name, code and creation date. They keep working in the integrations that already use them. New keys cannot be created here.

The only action is to delete. Deleting a key immediately interrupts the integrations that use it. For a new integration, create a key on the **Keys** tab.

## Good to know

- **The secret doesn't come back.** If the integration lost the secret, the screen does not show it again. Use **Rotate secret** and switch the secret in the integration within the chosen deadline.
- **Expired means stopped.** After the expiry date, the key stops working on its own and shows as **Expired**. To keep the same integration, create a new key.
- **Sandbox.** A key's environment is that of the account where it was created. A test account generates **Sandbox** keys, which don't access production data.
- **Who can change keys.** Viewing keys is one administrator permission. Creating, changing or revoking them is another. An administrator who can only view cannot create.
- **Activity for 30 days.** The **Activity** tab keeps the last 30 days. The account's general log keeps what the key did, even after it leaves the list.

## Frequently asked questions

**The integration suddenly stopped working.** Check three things:

1. The key's **Status**: suspended, expired or revoked.
2. Whether someone rotated the secret and the previous one's deadline has passed.
3. Whether the published permissions cover what the integration does.

The **Activity** tab shows who changed what.

**Can I give a key that only sees one product?** Yes. In the policy, choose **Specific products**. Permissions that are not product permissions (students, deliveries, settings) still apply to the whole account, and the screen tells you which ones.

**What is the difference between suspending and revoking?** Suspending is temporary: the key is refused until you reactivate it. Revoking is permanent.

**I changed the permissions and the integration still has no access.** The change only applies after **Publish changes**, on the **Permissions** tab.