Authentication

Every /api/v1/... endpoint requires a valid credential. The control plane supports several credential types and tries them as appropriate, so the same API works whether you are a person at a keyboard, a CI pipeline, or an in-cluster service.

Credential types

Type	How it looks	Best for
Single sign-on bearer token	Authorization: Bearer <jwt>	Apps and users with SSO
GitLab personal access token	Authorization: Bearer glpat-...	Direct API access as a GitLab user
GitLab CI job token	glcbt-..., injected as CI_JOB_TOKEN	Pipelines, with zero secret management
Service-account token	Projected token	In-cluster, machine-to-machine

All are presented as a bearer token in the Authorization header.

Getting a token

Interactive

Use the CLI to perform a browser sign-in and obtain a token:

nullctl auth token

Then use it:

curl -H "Authorization: Bearer $(nullctl auth token)" \
  https://<host>/api/v1/whoami

In GitLab CI

Nothing to do. GitLab provides CI_JOB_TOKEN automatically, and nullctl and the API accept it:

job:
  script:
    - curl -H "Authorization: Bearer $CI_JOB_TOKEN" \
        https://<host>/api/v1/emulators

Linking required

A CI job token authenticates as the GitLab user behind the pipeline. That user must be known to your tenant and granted access, or the call is rejected. If you get a 403 mentioning account linking, follow the link the API returns to associate your account. See Identity & Access.

Checking your identity & permissions

# Confirm who the token represents
GET /api/v1/whoami

# See everything you are allowed to do
GET /api/v1/permissions/me

# Check a single permission
GET /api/v1/permissions/check?relation=<rel>&object=<obj>

Account linking (VCS)

To connect your platform identity with a VCS provider (GitLab), the API drives an authorization flow:

• GET /api/v1/tenants/{id}/link/{vcsId} starts the link, and
• the provider redirects back to GET /api/v1/auth/callback to complete it.

The portal and CLI handle this for you. You will typically only encounter it during onboarding or the first time a CI identity needs linking.

Errors

Status	Meaning
401 Unauthorized	Missing or invalid token
403 Forbidden	Authenticated, but not permitted (or identity not linked)
404 Not Found	Resource does not exist or is not visible to you

Next steps

• Resources & Endpoints
• Identity & Access