API keys

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

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.

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

Frequently asked questions