Create and manage your API tokens

The client area's API lets your own tools read your services, their status and your invoices, and even act on your machines: an internal dashboard, a deployment script, your monitoring tool. Each tool identifies itself with a token you create under My profile › API. This page is for contacts with full access.

Create a token

1. Click New token.
2. Give it a Name that says what it's for, for example "GitLab production pipeline".
3. Choose when it Expires: 30 days, 90 days, 1 year (the default) or Never.
4. Tick its Scopes, or start from a preset with Start from: Dashboard (read only), Accounting (invoices), CI pipeline (deployments), Operations (machines).
5. Click Create, then copy the token shown (it starts with mmcp_).

The token is shown only once. Store it like a password, in a secret manager or your CI's secrets: anyone holding it acts with its scopes.

Scopes

Scopes come in three families:

• Read your data: read (services, status, incidents, maintenances, probes) and billing (invoices);
• Configure and annotate: HTTP probes, alert silences, deployment annotations, acknowledging ongoing problems, DNS records, SSH keys and startup scripts of your account;
• Act on your machines: Monit actions, VM power actions, on-demand backups, snapshots, VM firewall rules, private networks between your servers, reinstall and rescue mode of your VPS, restoring a VM from its backups, ordering a new VPS from a backup.

Scopes tagged "acts on your machines" or "destructive" deserve a short expiry and tools you trust. You can only tick what your own rights allow: a greyed-out scope matches a right you don't hold (VM power actions, for instance).

A token by roles: on some services only

When your company uses roles, the form offers two ways to define a token: By scopes (above) or By roles. A token by scopes acts on everything you have access to; a token by roles only does what the roles chosen allow, on the services and domains chosen.

1. In the form, click By roles.
2. Tick one or more Roles. Only the roles you hold yourself are offered.
3. Choose All services and domains or Some of them, then tick the services and domains concerned.
4. Click Create.

Example: for your deployment pipeline, a token "deploy-web" with the role "VM : accès complet" on web-9101 only. It can take a snapshot or reboot that machine; it sees neither your other machines nor your invoices.

Good to know:

• A token by roles has no scope: in the list, it shows its roles and what they apply to.
• It never goes beyond your own rights: if you lose a role, the token loses at once what that role gave it. A service account by roles keeps the roles it was given when made.
• A role you only hold on some services can only be given on those.

Manage tokens

The list shows each token's name, the start of the token, its scopes, who made it, when it was last used (or "never used") and its expiry date. Revoke turns it off immediately: programs using it stop working at once.

Service account: a token that belongs to the company

An ordinary token is tied to the person who made it: if that person's access is disabled or removed, the token stops. That's awkward for a robot (your deployment pipeline, your monitoring) that must keep running when a colleague leaves.

If our team opened the feature for your account, tick Service account when making the token:

• the token belongs to your company, not to you;
• it keeps the rights you have on the day it's made, even if your access changes later;
• it keeps working if you're disabled or removed from the team;
• its actions show in the activity log as « service-account », with the token's name.

In the list it carries the Service account label. It's revoked like any other token, by any contact with full access.

Example: you make the token « ci-deploy » as a service account for your pipeline. Six months later you change jobs and your access is removed: the pipeline keeps working.

Keep it for robots: for a person, an ordinary token is safer, since it stops with that person's access.

Good to know

• A token acts with the rights of the person who created it, checked on every call. If that contact is disabled, removed or loses a right, the token loses that access too.
• Your company's allowed addresses also apply to API calls.
• A company can have up to 20 active tokens. Revoke the ones you no longer use.
• A scope added later is never given to existing tokens: create a new token if you need it.