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:

1. OAuth2 tokens
2. Personal access tokens
3. 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.