What we need

[] API Token [] GitLab instance URL - Subdomain Gitlab “https://gitlab.example.com”

We are using personal access tokens to access Gitlab API. Follow these steps to generate a GitLab personal access token for accessing the GitLab REST API:

This means that the token used will inherit the user’s permissions at the organization level, so it is important to generate a personal access token from an account (or create a specific account) which administrative privileges to the Gitlab organization.

1. Sign in to GitLab

   • Sign in to your GitLab account (GitLab.com or self-hosted GitLab instance).

2. Access the Personal Access Tokens page

   • Click on your avatar in the top-right corner.
   • Select Edit profile.
   • On the left sidebar, select Access tokens.
   • Give it “read_api” permissions

3. Create a new token

   • Select Add new token.
   • In Token name, enter a descriptive name for your token (e.g., “API Access”).
   • Optional: In Token description, enter a description for the token.
   • In Expiration date, enter an expiration date for the token.
     • Note: Tokens without an expiry date are no longer supported in GitLab 16.0+.
     • The token expires at midnight UTC on the specified date.
     • If you don’t enter an expiry date, it will be set to 365 days from the current date.

4. Select the appropriate scopes

   • Choose the scopes based on what you need to access:
     • api: Full API access
     • read_api: Read-only API access
     • read_repository: Read-only repository access
     • write_repository: Read-write repository access
     • Other scopes as needed for your specific use case

5. Create the token

   • Select Create personal access token.
   • Important: Save the token somewhere secure immediately. You will not be able to see it again after leaving the page.

Using the Token with GitLab REST API

You can use your personal access token to authenticate with the GitLab REST API in one of the following ways:

Using the Authorization Header (Recommended)

Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN

Example with curl:

curl --header "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" "https://gitlab.example.com/api/v4/projects"

Using the PRIVATE-TOKEN Header

PRIVATE-TOKEN: YOUR_PERSONAL_ACCESS_TOKEN

Example with curl:

curl --header "PRIVATE-TOKEN: YOUR_PERSONAL_ACCESS_TOKEN" "https://gitlab.example.com/api/v4/projects"

Using a Query Parameter

https://gitlab.example.com/api/v4/projects?private_token=YOUR_PERSONAL_ACCESS_TOKEN

Example with curl:

curl "https://gitlab.example.com/api/v4/projects?private_token=YOUR_PERSONAL_ACCESS_TOKEN"

Security Considerations

• Store your token securely and treat it like a password.
• Use the minimum required scopes for your use case.
• Set an appropriate expiration date.
• Rotate tokens regularly.
• Use environment variables or secure secret management systems to store tokens in applications.
• Never commit tokens to source code repositories.

Item Checklist of what’s needed for integration

1. GitLab personal access token with appropriate scopes
2. Your GitLab instance URL (e.g., gitlab.com or your self-hosted instance URL)