Authenticate an AI coding agent to GitLab's REST API using a personal access token, choosing the right header, scope, base URL, and pagination/rate-limit handling.

Documented steps

1. In GitLab, create a personal access token (Edit profile > Access tokens) and select the api scope for full read/write API access, or read_api for read-only access; scopes are documented in the access token scopes table.
2. Authenticate REST calls with the PRIVATE-TOKEN header (recommended): curl --header "PRIVATE-TOKEN: <your_access_token>" --url "https://gitlab.example.com/api/v4/projects". Personal, project, and group access tokens can also be sent as an OAuth-style Authorization: Bearer <your_access_token> header.
3. If using OAuth 2.0 instead of a PAT, pass the token via the access_token query parameter or an Authorization: Bearer <OAUTH-TOKEN> header; OAuth 2.0 access tokens expire 2 hours after issue and must be refreshed with the refresh_token parameter.
4. All REST calls use the base path https://gitlab.example.com/api/v4 (or https://gitlab.com/api/v4 for GitLab.com).
5. For simple listing use the default offset pagination (page and per_page query params, max per_page 100); for large collections use keyset pagination where supported by adding pagination=keyset&order_by=<column>&sort=asc and follow only the Link: rel="next" header URL rather than building your own next-page URL.
6. Read the RateLimit-Limit, RateLimit-Name, RateLimit-Observed, RateLimit-Remaining, and RateLimit-Reset headers returned on every response to track quota; on a 429 response also read RateLimit-ResetTime and Retry-After (seconds to wait) before retrying.
7. Docs: https://docs.gitlab.com/api/rest/authentication/ https://docs.gitlab.com/api/rest/ https://docs.gitlab.com/security/tokens/access_token_scopes/ https://docs.gitlab.com/administration/settings/user_and_ip_rate_limits/#response-headers