Authentication
Most API requests require authentication, or will only return public data when authentication is not provided. For those cases where it is not required, this will be mentioned in the documentation for each individual endpoint. For example, the /projects/:id endpoint
There are three ways to authenticate with the GitLab API:
- OAuth2 tokens
- Personal access tokens
- Session cookies
If authentication information is invalid or omitted, an error message will be returned with status code 401:
{
"message": "401 Unauthorized"
}
OAuth2 tokens
You can use an OAuth2 token to authenticate with the API by passing it in either the access_token
parameter or the Authorization
header.
Example of using the OAuth2 token in a parameter:
curl https://gitlab.example.com/api/v4/projects?access_token=OAUTH-TOKEN
Example of using the OAuth2 token in a header:
curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api/v4/projects
Personal access tokens
You can use a personal access token to authenticate with the API by passing it in either the private_token
parameter or the Private-Token
header.
Example of using the personal access token in a parameter:
curl https://gitlab.example.com/api/v4/projects?private_token=9koXpg98eAheJpvBs5tK
Example of using the personal access token in a header:
curl --header "Private-Token: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects
Session cookie
When signing in to the main GitLab application, a _gitlab_session
cookie is set. The API will use this cookie for authentication if it is present.
The primary user of this authentication method is the web frontend of GitLab itself, without needing to explicitly pass an access token.