Act for an installation

Two Core endpoints take your plugin JWT: list repositories and mint an access token. Everything else takes an access token and goes to the repository’s region, except creating a repository, which takes an access token on a Core.

List repositories

GET https://{core}/api/v1/plugins/{slug}/installations/{installation_id}/repositories
Authorization: Bearer {plugin JWT}

The response lists every repository the customer selected:

{
  "repositories": [{
    "id": "repo_01M3...",
    "full_name": "acme/api",
    "clone_url": "https://aws-us-east-2.entire.io/et/acme/api.git",
    "entire_clone_url": "entire://aws-us-east-2.entire.io/et/acme/api",
    "placements": [
      {"region": "aws-us-east-2", "role": "processing_primary",
       "api_base_url": "https://aws-us-east-2.api.entire.io"},
      {"region": "aws-eu-central-1", "role": "mirror"}
    ]
  }],
  "next_cursor": null
}

Store a repository’s id, which never changes. Names and hosts can change, so list the repositories again rather than caching them for long. Customers change the selection without notice; this list is the authority on what you may touch.

Mint an access token

POST https://{core}/api/v1/plugins/{slug}/installations/{installation_id}/access-tokens
Authorization: Bearer {plugin JWT}
Content-Type: application/json

{"repository_id": "repo_01M3...", "permissions": {"contents": "read"}}

A successful mint answers 201:

{"token": "...", "username": "x-access-token", "expires_at": "2026-10-13T20:37:23Z", "permissions": {"contents": "read", "installations": "read"}}

Prefer a token scoped to one repository. See Access tokens for what each combination of repository and permissions reaches.

Errors

Status and code	Meaning	What to do
`401 unauthorized`	Entire could not verify your plugin JWT: wrong key, issuer, audience or times.	Check the claims table and your server clock.
`404 not_found`	The installation is gone, or the repository is not in it.	Stop acting for it. List the repositories again.
`400 unsupported_permission`	You asked for a permission you did not register.	Request only registered permissions.
`400 invalid_request`	You asked for `repositories:create` with a `repository_id`.	Mint a create token without a repository.
`409 coverage_changed`	The customer changed the selection while Entire minted the token, or you asked for a permission this installation doesn’t have yet.	Retry the mint. If it persists after a permission change, ask your Entire contact.
`429 rate_limited`	Too many mints for this installation.	Wait for `Retry-After`, in seconds, and cache tokens until shortly before they expire.
`403 forbidden`	Entire refused to issue the token.	Don’t retry in a loop. If it persists, ask your Entire contact.
`502`, `503`, `504`	Temporary.	Retry with backoff.

Error bodies are RFC 9457 problem documents, with a machine-readable code member.

Create a repository

A plugin registered with repositories:create can create repositories in the installation’s project. The customer sees “Create repositories in this project” on the install page. The permission only creates: it doesn’t read or write contents, delete repositories or change settings. To push to a repository you created, register contents:write too. First mint a token with no repository_id:

POST https://{core}/api/v1/plugins/{slug}/installations/{installation_id}/access-tokens
Authorization: Bearer {plugin JWT}
Content-Type: application/json

{"permissions": {"repositories": "create"}}

The response carries "permissions": {"repositories": "create", "installations": "read"}. The token reaches no repository. The installation-wide token, minted with every permission you registered, also creates. Then create the repository on the same Core:

POST https://{core}/api/v1/repos
Authorization: Bearer {access token}
Content-Type: application/json

{"name": "api", "objectFormat": "sha1"}

objectFormat is optional: sha1, the default, or sha256. Leave out projectId, and Core uses the installation’s project. Any other project answers 404. Plugins can’t set clusterHost or mirrorClusterSlugs. A successful create answers 201 with the repository:

{"repositoryId": "repo_01M3...", "name": "api", "owningProjectId": "...", "state": "provisioning", ...}

Store repositoryId. It is the id the repository list, access tokens and webhooks use. Core answers only once the installation covers the new repository, so you can mint a token for it right away. If the customer selected a list of repositories, the new one joins it. Every installation that covers it receives installation.repositories_added.

Wait for provisioning

When state is active, the repository is ready. When it is provisioning, Git and region API calls fail until it’s ready. List the installation’s repositories until the new one has a placement whose role is processing_primary, then send calls to that placement’s api_base_url.

Create errors

Core answers a refused create with an RFC 9457 problem document. Branch on its type, not on the status alone: 409 and 429 carry other conditions too.

Status and `type`	Meaning	What to do
`400`	The name or body is invalid, or you sent `clusterHost` or `mirrorClusterSlugs`.	Fix the request.
`401`	The token expired, or the customer uninstalled your plugin.	Mint a new token. Stop if the installation is gone.
`403`	The token lacks `repositories:create`.	Mint a token with `{"repositories": "create"}`.
`403` `https://entire.com/errors/plugins/installation-suspended`	The installation is suspended.	Stop creating until it is active again.
`404`	The project doesn’t exist, or isn’t the installation’s project.	Leave out `projectId`.
`409` `https://entire.com/errors/repo/name-in-use`	The project already has a repository with that name.	Pick another name, or list the repositories to find the existing one.
`429` `https://entire.com/errors/repo/create-limit-reached`	The installation reached its create limit.	Wait for `Retry-After`, in seconds.
`503`	Temporary.	Retry with backoff.

A create is not idempotent. If the connection drops before you read the response, list the installation’s repositories before you create again: a 409 can mean your own earlier create succeeded.

Limits and ownership

An installation can create 100 repositories in any 24 hours. To raise the limit, ask your Entire contact. The customer’s project owns every repository you create. The repositories stay when the customer uninstalls your plugin. The customer can remove one from the installation’s selection like any other repository, and then you lose access to it.

Documentation

Accounts and projects

Git

Trails

Sessions and checkpoints

Webhooks

Act for an installation

List repositories

Mint an access token

Errors

Create a repository

Wait for provisioning

Create errors

Limits and ownership

​List repositories

​Mint an access token

​Errors

​Create a repository

​Wait for provisioning

​Create errors

​Limits and ownership

List repositories

Mint an access token

Errors

Create a repository

Wait for provisioning

Create errors

Limits and ownership