Connectors API

Lists the API routes that list and remove the provider accounts linked to an owner, and the git credential route of a job.

Last updated 23 Oct 2026

On this page

GET /v1/connectors
DELETE /v1/connectors/{name}
POST /v1/connectors/{name}
POST /v1/git/credential

`GET /v1/connectors`

Lists the connectors of an owner, sorted by name.

Query	Required	Rule
`owner`	no	Your handle or a team slug. Your own handle when absent.

Response: 200, an array.

Field	Type	Meaning
`name`	string	The connector name, for example `acme-github-1`
`provider`	string	`github`, `gitlab`, `huggingface`, `dockerhub`, `ghcr`, `acr`, `oci`, `ecr` or `gar`
`kind`	string	`git`, `registry` or `modelhub`
`account`	string	The account or organization the provider reports
`state`	string	`connected`, `expired` or `revoked`
`detail`	string or null	A fixed sentence that says why the state is not `connected`
`registry`	object or null	The host and namespace of a registry connector

Errors: 403 as above, 404 not found for a team you are not in.

`DELETE /v1/connectors/{name}`

Removes a connector. The API marks it revoked, asks the provider to release the link, and deletes the stored credentials and then the connector. A run that is in progress fails at its next registry login with connector {name} is gone. A git credential request then answers no git connector of {owner} covers {host}/{repo}.

Response: 204, empty.

Errors:

403 — only a team admin can change team connectors; paused or removed, as above.
404 — not found: no such connector, or it belongs to a team you are not in.
500 — the connector could not be removed; try again.

`POST /v1/connectors/{name}`

Connects a container registry with a credential that you paste. Here {name} is the provider: dockerhub, ghcr, acr, oci, ecr or gar. Any other value is 404.

The API signs in to the registry with the credential first. It keeps the credential only when the registry accepts it. The response never holds the secret.

Field	Type	Required	Rule
`owner`	string	yes	Your handle, or a team where you are an admin
`host`	string	`oci`	`dockerhub` is always `docker.io`, and `ghcr` is always `ghcr.io`. For `ecr` and `gar` the API derives it from the account and the region. For `acr` the host ends in `.azurecr.io`. For `oci` it is a host name with no scheme and no path
`namespace`	string	`gar`	The path that images are pushed under, as lowercase segments separated by `/`. For `dockerhub` and `ghcr` it defaults to the user name in lowercase. For `gar` it is `PROJECT/REPOSITORY`
`username`	string	not `gar`	The user name of the credential. For `ecr` it is the access key ID
`secret`	string	yes	The access token or password. For `ecr` it is the secret access key. For `gar` it is the JSON key of the service account
`region`	string	`ecr`, `gar`	The region of the registry, for example `us-east-1` or `us-central1`
`role_arn`	string	no	`ecr` only. The IAM role that the API assumes before it asks for a login
`external_id`	string	no	`ecr` only. The external ID of that role

json

{ "owner": "acme", "username": "robot", "secret": "TOKEN" }

For ghcr, a body with no secret asks Kloudlite to sign in with the installation token of your GitHub connector. A superadmin turns this on in the setting ghcr_token_kind. Until then, the answer is 409.

json

{ "owner": "acme" }

Response: 201.

Field	Type	Meaning
`name`	string	The connector name, for example `acme-dockerhub-1`
`provider`	string	The provider
`account`	string	The user name
`registry`	object	The `host` and `namespace`

Errors:

403 — only a team admin can change team connectors.
404 — not found: an unknown provider, or a team you are not in.
409 — the owner has reached the connector limit. For ghcr without a secret, the text is GHCR sign-in through GitHub is not enabled; paste a personal access token or connect GitHub first; GHCR signs in through it.
422 — the registry refused this credential, or the host or the namespace breaks the rules, for example an ACR host must end in .azurecr.io.
502 — the registry could not be reached.

The API signs in again every hour. A registry that refuses the credential turns the connector to expired, with the detail the registry refused the credential; paste a new one.

`POST /v1/git/credential`

Answers a short-lived, read-only git credential for one repository. The git credential helper kl git-credential calls it each time git needs a credential. See Code in a job.

Three tokens are accepted:

The git credential token of a running pipeline job that asks for permissions.git: read. The job uses only the connectors of its owner. A job of a team never uses the connector of a member.
The git credential token of a sandbox that you made. It answers only while the sandbox runs.
The workspace tool token of a workspace or a bench.

A sandbox, a workspace and a bench use your own connector first, then the connector of the team. They never use the connector of another member or of another team. Every other token is 401. The git credential token is 401 on every other route. The connectors come from the token, never from the body.

Field	Type	Required	Rule
`protocol`	string	yes	`https`, the only value
`host`	string	yes	`github.com`, or the host of the GitLab of the region (`gitlab.com` by default). `kl git-credential` asks only for `github.com` and `gitlab.com`
`path`	string	no	The repository path that git sends, such as `acme/web.git`. The path ends at the first part that ends in `.git`, so `acme/web.git/info/lfs` is `acme/web`. A GitHub path is exactly `owner/name`

json

{ "protocol": "https", "host": "github.com", "path": "acme/web.git" }

Response: 200, with Cache-Control: no-store.

Field	Type	Meaning
`username`	string	`x-access-token` for GitHub. The deploy token user for GitLab
`password`	string	The token. Do not store it
`expiresAtMs`	integer	When the token stops working, in milliseconds since the epoch

Host	Credential
`github.com`	A token of the GitHub App installation of the account in the path, with `contents: read` on every repository of the installation. GitHub ends it after one hour
GitLab	A `read_repository` deploy token on the one picked project, made for this request. It ends one hour after the request at most, or earlier when the token that asked ends

Nothing revokes a credential that was given. It keeps working until it expires, up to one hour, also after the job or the sandbox ends. Only new requests are refused.

Errors:

401 — no token, or a token that is not one of the three above.
403 — job {key} did not ask for permissions.git: read; your access to {team} is paused; you are no longer a member of {team}.
404 — {host} is not a git host Kloudlite answers for; no git connector of {owner} covers {host}/{repo}; job {key} is not in this run; version {n} of {name} is gone; not found for a run of another owner.
409 — the run is over; job {key} is not running; the sandbox is over; connector {name} is expired; GitHub is not configured or GitLab is not configured.
422 — only https is answered; path is not a repository path; the body is not a git credential request.
429 — too many git credential requests; retry in a minute. The limit is 60 requests in one minute for each token.
502 — a fixed sentence of the provider, for example the provider refused the credential. The answer never holds the body of the provider.