12 routes of the published API contract, generated from it.
Auth: none
The page where the free credit is claimed, in a browser: the offer, the terms to accept, and the Claim button. Opened from the single-use link POST /v1/credits/claim-link makes (promigence credits claim); the link's token is the authority.
Auth: none
The page a browser lands on after sign-in; in headless mode it shows the code to paste back.
Auth: none
Start promigence login through the console: register the sign-in request (the PKCE S256 challenge, the state, the local port the CLI listens on or none to paste the code, the computer's name and the new key's name) and get the authorize page to open for it. The page shows the signed-in person what is asking, and when and from where the request was made; it refuses a request that is more than ten minutes old or was already answered. promigence login does this for you.
base64url(sha256(code_verifier)): the PKCE challenge (RFC 7636), 43 characters.S256, the only method accepted.cli@<device>).GET /v1/auth/config's loopback_redirect_uris. Absent: the page shows the code, to paste into the client.github or google: a browser that is not signed in goes straight to that sign-in method.creq_…: names the request.Auth: none
Finish promigence login after you authorized the CLI in the browser: exchange the one-time code the authorize page gave the CLI, with the PKCE verifier whose S256 challenge the CLI sent there, for an API key (api_key, in this answer only). A code works once, for five minutes, and only with its own verifier and the redirect it was delivered to; any other attempt uses it up. promigence login does this for you; GET /v1/auth/config names the authorize page in console_authorize_url.
mint_key was asked for.mint_key was asked for.promigence login --ref): what became of it. A code that does not apply never stops the sign-in.Auth: none
What promigence login needs to start a sign-in: the identity domain, client id and scopes, and the console page where you authorize the CLI (console_authorize_url, when it is offered).
promigence login): the client registers its request first (POST /v1/auth/cli/requests, which answers the page's address for it); the page shows the request and asks for a click, then hands the client a one-time code it exchanges at POST /v1/auth/cli/token. Absent when that page is not offered; a client then signs in through authorize_url as before.email, google, github). A client that asks the sign-in pages for one method passes the label as their identity_provider, except email, which is the pages' own form and needs none.POST /v1/auth/invite) before it starts the sign-in (promigence signup). An existing account signs in as before either way.Auth: none
Redeem an invite code for one sign-in attempt, before the sign-in starts (promigence signup does it for you). Only while GET /v1/auth/config says invite_mode: the attempt with the same login nonce may then create an account within expires_in_s. Every code that does not redeem gets the same 403 invite_invalid; attempts are rate limited per address.
Auth: none
Give back the place a redeemed invite code holds for a sign-in attempt that ended without an account (it timed out or was cancelled), so the next attempt can redeem the code at once (promigence signup does it for you). Only the attempt's own login nonce names its hold, and a hold that already created an account is never given back. Always 200 {released}; rate limited per address.
Auth: sign-in token
Exchange an identity token for a Promigence API key. The first call for an identity creates the user, the org, its free credit offer (claimed later in a browser, POST /v1/credits/claim-link) and the first key, in one transaction. One account per verified email address: a first sign-in whose address already has an account through another sign-in method creates nothing and is answered 409 account_exists, naming the method to sign in with. While invite mode is on, a first sign-in whose attempt redeemed no invite code (POST /v1/auth/invite) creates nothing and is answered 403 invite_required; an existing account is never asked for a code.
cli, at most 64 characters).mint_key was asked for.mint_key was asked for.promigence login --ref): what became of it. A code that does not apply never stops the sign-in.Auth: API key
List your org's keys: with an API key, its own project's; with an identity token, every project's. ?all=1 includes revoked ones.
Auth: API key
Mint a key. api_key is in the 201 response and is never retrievable again. A key minted by a key stays in that key's project, and is revoked when that key is; a service key cannot mint. A key does not expire unless you give it an expiry; past it, the key answers 401 key_expired, and the org's owners are mailed 14 and 3 days before.
full (the default) | run (sandboxes, runs and builds, whose runs can use the project's stored secrets; no changes to secrets, keys or billing) | read (reads everything in the project, file contents and command output included; changes nothing).2027-01-31) or a UTC time ending in Z.cli, at most 64 characters.full, run (sandboxes, runs and builds, whose runs can use the project's stored secrets; no changes to secrets, keys or billing) or read (reads everything in the project, file contents and command output included; changes nothing).DELETE /v1/keys/{key_id}: the key ids this revocation also revoked, because the key had minted them (directly or further down). Absent when the key replaced itself (?reason=replaced), which revokes nothing it minted.POST /v1/keys; it cannot be retrieved afterwards.null for a key minted by another key.null = it does not expire (the default). An expired key answers key_expired.null for a key that has never been used.null for a key minted by a sign-in. Revoking a key revokes every key it minted, and every key those minted./24 or an IPv6 /64, never a full address, with when it was first and last seen there. On the key list; absent elsewhere.DELETE /v1/keys/{key_id}.null while the key still works.Auth: API key
Revoke a key, and every key it minted (and every key those minted): also_revoked lists them. Your own key is yours to revoke; another member's key, or any service key, needs the owner role; a service key may revoke only itself. ?reason=replaced or ?reason=logout from the key itself (the CLI rotating or ending its session key) revokes only that key.
full, run (sandboxes, runs and builds, whose runs can use the project's stored secrets; no changes to secrets, keys or billing) or read (reads everything in the project, file contents and command output included; changes nothing).DELETE /v1/keys/{key_id}: the key ids this revocation also revoked, because the key had minted them (directly or further down). Absent when the key replaced itself (?reason=replaced), which revokes nothing it minted.POST /v1/keys; it cannot be retrieved afterwards.null for a key minted by another key.null = it does not expire (the default). An expired key answers key_expired.null for a key that has never been used.null for a key minted by a sign-in. Revoking a key revokes every key it minted, and every key those minted./24 or an IPv6 /64, never a full address, with when it was first and last seen there. On the key list; absent elsewhere.DELETE /v1/keys/{key_id}.null while the key still works.Auth: API key
Mint a key in an organization you belong to, in one of its projects. With an API key, only in that key's own organization; with a sign-in, in any of yours. service: true (owners only) makes a project's key that keeps working when the member who minted it leaves, and that cannot manage the organization; any other key is revoked with its minter's membership.
full (the default) | run (sandboxes, runs and builds, whose runs can use the project's stored secrets; no changes to secrets, keys or billing) | read (reads everything in the project, file contents and command output included; changes nothing).Z.cli, at most 64 characters.full, run (sandboxes, runs and builds, whose runs can use the project's stored secrets; no changes to secrets, keys or billing) or read (reads everything in the project, file contents and command output included; changes nothing).null = it does not expire (the default).