Postwind Pre-release Download
Docs menu revoke_api_key

Generated from Postwind commit a19b2e4 OpenAPI 0.1.0 synced

Keysrequires confirm HTTP API

DELETE/api/v1/projects/{project_id}/keys/{key_id}

revoke_api_key

Revokes an API key of a project for good: every request with it is refused from then on.

Call it
when a key leaked or is no longer used.
Needs
an admin key with project_id, or a project key with scope keys (its own project; the argument is ignored; it may revoke itself), and confirm: true; without it the call changes nothing and tells what it would do.
Returns
outcome (would_revoke, revoked, already_revoked), effect in words and the key as list_api_keys shows it after the call; the API’s DELETE /api/v1/projects/{project_id}/keys/{key_id} answers 204.

Arguments

  • object
  • key_idstring · uuidrequired

    The key’s id, as list_api_keys gives it.

  • confirmboolean

    true revokes the key. Without it the call only tells what would happen and changes nothing.

    default false

  • project_idstring · uuid | null

    The key’s project. An admin key must pass it; a project key’s own project is used and this is ignored.

No other arguments are accepted.

Result

The result comes back as structuredContent, with the same JSON as a text block.

  • object · all fields required
  • effectstring

    The outcome in words, for the agent and its user.

  • keyApiKey

    The key as it is now.

    10 fields
    • ApiKey object · all fields required
    • created_atstring · date-time
    • expires_atstring · date-time | null

      null: never.

    • idstring · uuid

      What revoking the key takes.

    • kindKeyKind

      The kind of an API key.

      admin Everything, projects and admin keys included.

      project One project, within its scopes.

    • last_used_atstring · date-time | null

      When the key was last used; null: not recorded yet.

    • namestring
    • prefixstring

      The public part of the key string, pw_<adm|prj>_<prefix>_...: how to tell which key a client holds.

    • project_idstring · uuid | null

      The key’s project; null for an admin key.

    • revoked_atstring · date-time | null

      When the key was revoked; null while it is not.

    • scopesarray of KeyScope

      What the key may do; every scope for an admin key.

  • outcomeRevocationOutcome

    What a revocation did.

    would_revoke A dry run: nothing changed; a call with confirm: true revokes.

    revoked Revoked now.

    already_revoked Revoked before; nothing changed.

Definitions

ApiKey

An API key, without its secret (list_api_keys, list_admin_keys).

  • object · all fields required
  • created_atstring · date-time
  • expires_atstring · date-time | null

    null: never.

  • idstring · uuid

    What revoking the key takes.

  • kindKeyKind

    The kind of an API key.

    admin Everything, projects and admin keys included.

    project One project, within its scopes.

  • last_used_atstring · date-time | null

    When the key was last used; null: not recorded yet.

  • namestring
  • prefixstring

    The public part of the key string, pw_<adm|prj>_<prefix>_...: how to tell which key a client holds.

  • project_idstring · uuid | null

    The key’s project; null for an admin key.

  • revoked_atstring · date-time | null

    When the key was revoked; null while it is not.

  • scopesarray of KeyScope

    What the key may do; every scope for an admin key.

KeyKind

The kind of an API key.

string · enum

admin Everything, projects and admin keys included.

project One project, within its scopes.

KeyScope

A right of a project key. An admin key has all of them.

string · enum

  • read
  • write
  • send
  • keys

RevocationOutcome

What a revocation did.

string · enum

would_revoke A dry run: nothing changed; a call with confirm: true revokes.

revoked Revoked now.

already_revoked Revoked before; nothing changed.

Errors

A failed call answers isError: true with a code from the same table as the HTTP API, and detail. How tools report errors

HTTP API

The same operation over HTTP: DELETE /api/v1/projects/{project_id}/keys/{key_id}