Akter

API keys

API keys let programs and agents act in an organization with the scopes chosen at creation.

List⁠

GEThttps://api.akter.dev/v1/organizations/{organization}/api-keys
apiKeys.listBearer token

List an organization's API keys with their scopes; secrets are never listed.

Path parameters

  • organizationstringrequired

    An organization's name, unique across Akter Cloud. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

Query parameters

  • cursorstring

    The nextCursor of the previous page.

  • limitinteger

    At most this many items, 1 to 100. Defaults to 50.

Response 200ApiKeyPage

  • itemsApiKey[]required
  • items[].appsstring[]

    Allowed app names in this organization. Omit for organization-wide access. App-restricted keys cannot read organization-wide usage.

  • items[].createdAtstringrequired
  • items[].createdBystring

    The person who created the key, who is asked to approve its dangerous actions.

  • items[].expiresAtstring

    When the key stops getting tokens. Every key made since Phase 8 has one.

  • items[].idstringrequired

    An opaque id that starts with key_.

  • items[].lastUsedAtstring
  • items[].namestringrequired

    A name for people to read, 1 to 100 characters.

  • items[].scopes("deploy" | "usage" | "call" | "read" | "export" | "delete" | "branch" | "snapshot" | "fork")[]required

    What the key may do: one or more scopes.

  • items[].spendCapinteger

    The key's monthly cap in whole US dollars. Every key made since Phase 8 has one; an older key without it is bounded by its organization's cap.

  • items[].startstringrequired

    The first characters of the secret, to tell keys apart.

  • nextCursorstring

    Pass as cursor for the next page.

Errors

  • 401UnauthorizedError
  • 403ForbiddenError
  • 404NotFoundError | FeatureNotEnabledError
  • 503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError

Create⁠

POSThttps://api.akter.dev/v1/organizations/{organization}/api-keys
apiKeys.createBearer token

Create an API key with at least one scope, optionally limited to some apps, with a monthly spend cap and an expiry. The secret is returned once, in this response.

Path parameters

  • organizationstringrequired

    An organization's name, unique across Akter Cloud. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

Request bodyCreateApiKey

  • appsstring[]

    Allowed app names in this organization. Omit for organization-wide access. App-restricted keys cannot read organization-wide usage.

  • expiresAtstringrequired

    When the key stops getting tokens. Required: every key expires (Decision 11A).

  • namestringrequired

    A name for people to read, 1 to 100 characters.

  • scopes("deploy" | "usage" | "call" | "read" | "export" | "delete" | "branch" | "snapshot" | "fork")[]required

    What the key may do: one or more scopes.

  • spendCapintegerrequired

    The most the work this key starts may cost in a calendar month, in whole US dollars. Raising it needs a person's confirmation.

Response 201CreatedApiKey

  • keyApiKeyrequired
  • key.appsstring[]

    Allowed app names in this organization. Omit for organization-wide access. App-restricted keys cannot read organization-wide usage.

  • key.createdAtstringrequired
  • key.createdBystring

    The person who created the key, who is asked to approve its dangerous actions.

  • key.expiresAtstring

    When the key stops getting tokens. Every key made since Phase 8 has one.

  • key.idstringrequired

    An opaque id that starts with key_.

  • key.lastUsedAtstring
  • key.namestringrequired

    A name for people to read, 1 to 100 characters.

  • key.scopes("deploy" | "usage" | "call" | "read" | "export" | "delete" | "branch" | "snapshot" | "fork")[]required

    What the key may do: one or more scopes.

  • key.spendCapinteger

    The key's monthly cap in whole US dollars. Every key made since Phase 8 has one; an older key without it is bounded by its organization's cap.

  • key.startstringrequired

    The first characters of the secret, to tell keys apart.

  • secretstringrequired

    The bearer secret. It is returned once and never again.

Errors

  • 401UnauthorizedError
  • 403ForbiddenError
  • 404NotFoundError | FeatureNotEnabledError
  • 503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError

Update⁠

PATCHhttps://api.akter.dev/v1/organizations/{organization}/api-keys/{key}
apiKeys.updateBearer tokenSafe to retryAsks a person to confirm

Change an API key's monthly spend cap. An API key changing it needs a person's approval.

Path parameters

  • organizationstringrequired

    An organization's name, unique across Akter Cloud. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

  • keystringrequired

    An opaque id that starts with key_.

Request bodyUpdateApiKey

  • spendCapintegerrequired

    The most the work this key starts may cost in a calendar month, in whole US dollars. Raising it needs a person's confirmation.

Response 200ApiKey

  • appsstring[]

    Allowed app names in this organization. Omit for organization-wide access. App-restricted keys cannot read organization-wide usage.

  • createdAtstringrequired
  • createdBystring

    The person who created the key, who is asked to approve its dangerous actions.

  • expiresAtstring

    When the key stops getting tokens. Every key made since Phase 8 has one.

  • idstringrequired

    An opaque id that starts with key_.

  • lastUsedAtstring
  • namestringrequired

    A name for people to read, 1 to 100 characters.

  • scopes("deploy" | "usage" | "call" | "read" | "export" | "delete" | "branch" | "snapshot" | "fork")[]required

    What the key may do: one or more scopes.

  • spendCapinteger

    The key's monthly cap in whole US dollars. Every key made since Phase 8 has one; an older key without it is bounded by its organization's cap.

  • startstringrequired

    The first characters of the secret, to tell keys apart.

Errors

  • 401UnauthorizedError
  • 403ForbiddenError
  • 404NotFoundError | FeatureNotEnabledError
  • 428ConfirmationRequiredError
  • 503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError

Revoke⁠

DELETEhttps://api.akter.dev/v1/organizations/{organization}/api-keys/{key}
apiKeys.revokeBearer token

Revoke an API key. Its secret gets no new token at once; a token it already holds works until it expires, at most a minute.

Path parameters

  • organizationstringrequired

    An organization's name, unique across Akter Cloud. 1 to 63 characters: a lowercase letter, then lowercase letters, digits or single hyphens, ending in a letter or digit.

  • keystringrequired

    An opaque id that starts with key_.

Response 204<No Content>

Errors

  • 401UnauthorizedError
  • 403ForbiddenError
  • 404NotFoundError | FeatureNotEnabledError
  • 428ConfirmationRequiredError
  • 503ActorUnavailableError | AuthUnavailableError | BillingUnavailableError | BuildStorageUnavailableError | ExecUnavailableError