Skip to main content
Video tutorial · 1:01

API tokens

An API token lets a program call the Merge Pilot REST API without a browser session. There are two kinds:

KindMade inActs asRole
ServiceCompany → API tokens → Service API tokensThe company (for CI, scripts and other automation)Its own role, chosen when the token is made
PersonalMy profile → Personal API tokensThe person who made itThat 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 doesDefaultAllowed valuesAPI field (JSON name)
NameTells the token apart in the listEmpty; the button stays disabled until a name is typedRequired, at most 100 characters. Leading and trailing spaces are removedname
Role (service tokens only)The role the token acts withAuditorCompany admin, Policy manager, Auditor or User. A token can never be a platform admin. See Roles and usersrole (company_admin, policy_manager, auditor, user)
Valid for (days)The token expires this many days after it is made901 to 365expires_in_days

The expiry cannot be extended. Make a new token before the old one expires.

Who can make tokens​

KindWho can make, list and revoke them
ServiceCompany admins of the company, and platform admins. They see and revoke every service token of the company
PersonalAny 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 doesDefaultAllowed valuesWho can change itAPI field (JSON name)
Let people make personal API tokensWhen 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 againOnOn or offCompany admins and platform admins, from a signed-in sessionpersonal_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 pathWhoWhat
GET /api/v1/companies/{id}/api-tokensCompany adminList the company's service tokens, newest first
POST /api/v1/companies/{id}/api-tokensCompany adminMake a service token: name, role, expires_in_days
DELETE /api/v1/companies/{id}/api-tokens/{tokenId}Company adminRevoke a service token
GET /api/v1/auth/me/api-tokensAnyone with a companyList your personal tokens
POST /api/v1/auth/me/api-tokensAnyone with a companyMake a personal token: name, expires_in_days
DELETE /api/v1/auth/me/api-tokens/{tokenId}Anyone with a companyRevoke 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 →

Automate with the API and Service TokensYouTube ↗