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):
| Kind | Acts as | Role |
|---|---|---|
| Service token | The company: CI jobs, scripts and other automation | Its own role, chosen when it is made: company admin, policy manager, auditor or user |
| Personal token | The person who made it | That 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
Beareris 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 with401unless 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
GETrequests. ThreePOSTrequests that change nothing are allowed too: trying policies (POST /companies/{id}/policies/simulate), the monitoring report (POST /companies/{id}/monitoring/report) andPOST /projects/evidence; so are changes to the person's own profile (PUT /auth/me) and signing out. Anything else is answered403with 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:
| Request | What it does |
|---|---|
POST /merge-requests/{id}/votes | Approve or reject a change approval (see Approving and rejecting) |
POST /merge-requests/{id}/assign-me | Take a change approval |
POST /merge-requests/{id}/risk-allow | Accept the risk of a risk-held merge request |
POST /merge-requests/{id}/freeze-release | Let a change held by a change freeze go ahead |
POST /merge-requests/{id}/rejection/withdraw | Withdraw a rejection |
POST /delegations, DELETE /delegations/{id} | Name or remove a stand-in |
GET /auth/me | Read the signed-in account |
GET /auth/me/sso | Read the signed-in account's identity providers |
GET /auth/me/notification-preferences, PUT /auth/me/notification-preferences | Read 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 answered404, 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 readcompany_idfromGET /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 endpoint | How 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
| Status | error.message | When |
|---|---|---|
401 | unauthorized | No Authorization header and no session |
401 | invalid, expired or revoked API token | The 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) |
401 | invalid or expired token, session is no longer valid | A browser session that expired or was ended, or a bearer value that is not an API token |
403 | your role does not allow this | The role does not allow the request |
403 | this role can only read | An auditor tried to change something |
403 | this needs a signed-in session: API tokens cannot change security settings | A token was used where a person must sign in |
403 | a service token acts for no person: use a personal token or a signed-in session | A service token was used where a person must act |
403 | password change required | A browser session whose password must be changed first, with error.code password_change_required |
500 | failed to verify the API token | The 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.
Related pages
- API tokens: making, revoking and allowing tokens.
- Roles and users: what each role may do.
- Conventions: envelope, errors, pagination and rate limits.
- Examples: worked requests.
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →