Skip to main content
Video tutorial · 1:01

API authentication

Programs call the REST API with an API token. The browser interface uses a signed-in session instead. This page explains how a request is authenticated, what a token may do, and which company a request acts on.

API tokens​

There are two kinds of token, both described in API tokens (how to make, list and revoke them, their expiry, and when they stop working):

KindActs asRole
Service tokenThe company: CI jobs, scripts and other automationIts own role, chosen when it is made: company admin, policy manager, auditor or user
Personal tokenThe person who made itThat person's current role

Every token starts with mpt_.

The Authorization header​

Send the token as a bearer credential on every request:

curl -H "Authorization: Bearer mpt_..." https://<your-host>/api/v1/merge-requests
  • The scheme name Bearer is not case-sensitive.
  • A request with a token is authenticated by the token only: browser cookies sent with it are ignored, and the CSRF check does not apply to it (see Browser sessions).
  • A bearer value that does not start with mpt_ is not an API token: it is checked as a browser session instead, and refused with 401 unless it is one.

What a token may do​

A token has no scopes of its own: what it may do is what its role may do, as listed in Roles and users. A request the role does not allow is answered 403 with your role does not allow this.

  • Auditor tokens only read. A service token with the auditor role, or a personal token of an auditor, may send GET requests. Three POST requests that change nothing are allowed too: trying policies (POST /companies/{id}/policies/simulate), the monitoring report (POST /companies/{id}/monitoring/report) and POST /projects/evidence; so are changes to the person's own profile (PUT /auth/me) and signing out. Anything else is answered 403 with this role can only read.
  • Each token belongs to one company. It reads and changes that company only (see Choosing the company).

What a token may not do​

Some requests need a person signed in and refuse every token, whatever its role. They are answered 403 with this needs a signed-in session: API tokens cannot change security settings:

  • making, listing and revoking API tokens;
  • signing out everywhere, which revokes the person's personal tokens;
  • changing the own password, which revokes every session and token of the person;
  • unlinking one of the own identity providers or GitLab or GitHub accounts, and confirming an account link from My profile;
  • managing users, including reading the user list;
  • the company's identity providers, including reading them;
  • testing the company's LDAP directory, mail settings and container registry sign-ins, and sending a test to a notification route;
  • approving or rejecting a control change that waits for four-eyes review;
  • platform settings, managing the license, and creating or deleting companies (platform admins only).

Because no token can call them, these requests are not in the API reference.

A token may change the company's other settings (PUT /companies/{id}, company admin role), but not its sign-in settings, LDAP directory, mail settings, four-eyes review, the personal-token setting or how long the audit log is kept. Such a request is answered 403 with API tokens cannot change <fields>: use a signed-in session, naming the fields: sign_in, ldap, smtp, governance, personal_api_tokens, audit_retention_days.

What a service token may not do​

A service token acts for no person. These requests act as a person and refuse service tokens with 403 a service token acts for no person: use a personal token or a signed-in session:

RequestWhat it does
POST /merge-requests/{id}/votesApprove or reject a change approval (see Approving and rejecting)
POST /merge-requests/{id}/assign-meTake a change approval
POST /merge-requests/{id}/risk-allowAccept the risk of a risk-held merge request
POST /merge-requests/{id}/freeze-releaseLet a change held by a change freeze go ahead
POST /merge-requests/{id}/rejection/withdrawWithdraw a rejection
POST /delegations, DELETE /delegations/{id}Name or remove a stand-in
GET /auth/meRead the signed-in account
GET /auth/me/ssoRead the signed-in account's identity providers
GET /auth/me/notification-preferences, PUT /auth/me/notification-preferencesRead or change the person's own notification emails

Use a personal token for these: it acts as its person, with their linked VCS accounts and their role.

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

Choosing the company​

A token always acts on its own company. The company_id query parameter and the X-Company-ID header are ignored for it, and so they are for every person who belongs to a company.

  • Paths with a company in them (/companies/{id}/...) must name your own company. Another company's ID is answered 404, as are the IDs of anything else that belongs to another company, so IDs cannot be probed.
  • To learn your company's ID, call GET /companies: for a token it lists exactly one company, its own. A personal token can also read company_id from GET /auth/me.

Only platform admins choose a company, and they have no API tokens (they belong to no company), so this concerns their signed-in sessions:

Kind of endpointHow a platform admin chooses the company
Per-company requests, such as /projects, /merge-requests/lookup, /delegations, /mptracker/...?company_id=<id> or the header X-Company-ID: <id>. Without either, the request is answered 400 select a company
Lists across companies, such as /merge-requests and /audit-logs?company_id=<id>. Without it, the list covers every company. Some of them need it: the compliance report answers 400 company_id is required for compliance reports without it
Paths with the company in them, /companies/{id}/...The {id} in the path

The reference marks which parameter each endpoint takes.

Browser sessions​

When a person signs in to the interface, the session is set in httpOnly cookies (access_token, refresh_token) and no token is handed to the page. Sessions, their lifetime and what ends them are described in Sign-in → Sessions. For programs, use API tokens instead. The endpoints of the browser sign-in flow (signing in and out, single sign-on and VCS sign-in redirects) are not in the API reference: they work only in a browser, and API tokens cannot call them.

For completeness: requests that use the session cookies and change something (POST, PUT, PATCH, DELETE) must also send the header X-CSRF-Token with the value of the csrf_token cookie, which Merge Pilot sets on its answers. Without it, or with a wrong value, the request is answered 403 with CSRF token missing or invalid. Requests with an API token never need it.

Sign-in requests have their own, stricter rate limit (see Conventions → Rate limits).

Failed authentication​

Statuserror.messageWhen
401unauthorizedNo Authorization header and no session
401invalid, expired or revoked API tokenThe token is unknown, revoked or expired; its company is deactivated; a personal token's person was deactivated, moved, given another role, changed their password or signed out everywhere; or the company does not allow personal tokens (see When a token stops working)
401invalid or expired token, session is no longer validA browser session that expired or was ended, or a bearer value that is not an API token
403your role does not allow thisThe role does not allow the request
403this role can only readAn auditor tried to change something
403this needs a signed-in session: API tokens cannot change security settingsA token was used where a person must sign in
403a service token acts for no person: use a personal token or a signed-in sessionA service token was used where a person must act
403password change requiredA browser session whose password must be changed first, with error.code password_change_required
500failed to verify the API tokenThe token could not be checked at that moment. Try again

A 401 never says which of the reasons applied. All answers use the error envelope described in Conventions.

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 ↗