API tokens
An API token lets a program call the Merge Pilot REST API without a browser session. There are two kinds:
| Kind | Made in | Acts as | Role |
|---|---|---|---|
| Service | Company → API tokens → Service API tokens | The company (for CI, scripts and other automation) | Its own role, chosen when the token is made |
| Personal | My profile → Personal API tokens | The person who made it | That person's current role |
A program sends the token in the Authorization header:
curl -H "Authorization: Bearer mpt_..." https://merge-pilot.example.com/api/v1/merge-requests
How a token looks
- Every token starts with
mpt_, so a leaked token is easy to find in logs and code. - The token is shown once, right after Make token, with the note Copy the token now: it is not shown again. Merge Pilot keeps only a hash of it and cannot show it again. If it is lost, revoke it and make a new one.
- Lists show each token by its name and its public part,
mpt_<lookup>_…, so tokens can be told apart without revealing them. - Each token in a list shows when it expires (or Revoked), and when it was last used (never used until its first call). The last use is updated at most once a minute.
Making a token
| Setting (label in the UI) | What it does | Default | Allowed values | API field (JSON name) |
|---|---|---|---|---|
| Name | Tells the token apart in the list | Empty; the button stays disabled until a name is typed | Required, at most 100 characters. Leading and trailing spaces are removed | name |
| Role (service tokens only) | The role the token acts with | Auditor | Company admin, Policy manager, Auditor or User. A token can never be a platform admin. See Roles and users | role (company_admin, policy_manager, auditor, user) |
| Valid for (days) | The token expires this many days after it is made | 90 | 1 to 365 | expires_in_days |
The expiry cannot be extended. Make a new token before the old one expires.
Who can make tokens
| Kind | Who can make, list and revoke them |
|---|---|
| Service | Company admins of the company, and platform admins. They see and revoke every service token of the company |
| Personal | Any person who belongs to a company, for themselves only, when the company allows personal tokens (below). Nobody else can see or revoke a person's personal tokens. Auditors make and revoke personal tokens too; their tokens only read, as the auditor does. Platform admins who belong to no company have no personal tokens |
Tokens are made and revoked only from a signed-in session: a token cannot make or revoke tokens. For the same reason a token cannot sign its person out everywhere or change its person's password, which both revoke their personal tokens, nor unlink one of their identity providers or GitLab or GitHub accounts.
Allowing personal tokens
On Company → API tokens, the company admin decides whether people may make their own tokens.
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field (JSON name) |
|---|---|---|---|---|---|
| Let people make personal API tokens | When on, people make personal tokens in My profile. When off, nobody can make one, and every existing personal token of the company stops working once the page is saved; turned back on, the tokens that have not expired or been revoked work again | On | On or off | Company admins and platform admins, from a signed-in session | personal_api_tokens |
Turning the setting off does not revoke the tokens: they are refused while it is off, and tokens that have not expired or been revoked work again if it is turned back on.
When the company has Review control changes turned on (Company → Governance), a change to this setting waits until another administrator approves it.
What a token can do
A token can do what its role allows (see Roles and users), with these limits:
- No security settings. A request with a token is refused when it changes users, how people sign in, identity providers, the company directory (LDAP), mail settings, four-eyes review, the personal-token setting, how long the audit log is kept, platform settings or the license, when it decides a held control change, or when it makes or revokes tokens (signing out everywhere included). These need a person signed in.
- Auditor tokens only read, as an auditor does.
- Service tokens act for no person. They cannot vote on a change approval, withdraw a rejection, take a change approval over, accept a risk, let a change go ahead during a change freeze, name a stand-in, or change personal notification emails. Use a personal token or a signed-in session for these.
- Four-eyes review: a control change requested with a service token counts as requested by the person who made the token, so that person cannot approve it.
Before a token expires
A token lasts at most 365 days and cannot be extended. The token lists show when each expires. 14 days and again 3 days before a token expires, Merge Pilot says what to do: create a new token, put it where the old one is used, then delete the old one.
- A personal token: its owner gets API token expiring (
api_token_expiring). - A service token: the company admins get Service API token expiring (
service_token_expiring).
When a token stops working
A token is refused when:
- it was revoked, or it has expired;
- its company is deactivated.
A personal token also stops working when its person:
- is deactivated, or moved to another company;
- gets a different role;
- changes their password, or an administrator resets it;
- uses sign out everywhere in My profile;
and while the company does not allow personal tokens.
In the cases of the person (deactivated, moved, a new role, a new password, signing out everywhere) the token stops for good and the list shows it as Revoked: make a new one. While the company is deactivated or does not allow personal tokens, tokens are refused but not revoked: they work again when it changes back, until they expire.
Revoking a token
Select Revoke next to the token and confirm. Programs using it stop working at once. A revoked token stays in the list, marked Revoked, and cannot be used again.
Making and revoking tokens is recorded in the audit log (api_token_created, api_token_revoked).
API
| Method and path | Who | What |
|---|---|---|
GET /api/v1/companies/{id}/api-tokens | Company admin | List the company's service tokens, newest first |
POST /api/v1/companies/{id}/api-tokens | Company admin | Make a service token: name, role, expires_in_days |
DELETE /api/v1/companies/{id}/api-tokens/{tokenId} | Company admin | Revoke a service token |
GET /api/v1/auth/me/api-tokens | Anyone with a company | List your personal tokens |
POST /api/v1/auth/me/api-tokens | Anyone with a company | Make a personal token: name, expires_in_days |
DELETE /api/v1/auth/me/api-tokens/{tokenId} | Anyone with a company | Revoke one of your personal tokens |
These calls need a signed-in session. The answer to a POST carries the token once, in token. Each token in a list has id, kind (service or personal), name, role (service tokens), lookup, expires_at, last_used_at, created_by, created_at and revoked_at.
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →