Skip to content

API keys

Rotate an API key

Creates a new key with the same name, scope and IP allowlist and returns it with its secret key, shown once. The old key keeps working for grace_hours, then is revoked automatically. For a blocked key the old key stops at once (grace_hours is ignored). Recorded in the audit log as api_key.rotated.

POST/api/v1/keys/{id}/rotate
  • Console only: owner or admin
  • Workspace: X-Tenant-ID

Path parameters

  • iduuidrequired

    Key id (not the key itself).

    Example
    8192a3b4-c5d6-4e7f-8091-a2b3c4d5e6f7

Headers

  • Cookiestringrequired

    The whatsappx_session cookie the app sets when you sign in. Browsers send it automatically; API keys are not accepted on this endpoint.

    Example
    whatsappx_session=…
  • X-Tenant-IDuuidrequired

    Workspace id. Required for session requests. You can pass ?tenant=<id> instead.

    Example
    8d0f6c2e-3b1a-4c55-9a7e-2f4b6d1e9c30

Body

application/json
  • grace_hoursintegeroptional

    How long the old key keeps working, so you can deploy the new key first. 0 stops it now. Always 0 for a key blocked as leaked.

    Constraints
    0–72.
    Default
    24
    Example
    24

Response

201 Createdapplication/json

  • iduuid

    Key id. Use it to delete the key.

  • namestring

    Name you gave the key.

  • prefixstring

    First 16 characters of the key (for example pk_live_3f9a1c0b), so you can recognise it.

  • scopeenum

    read (GET requests only), write (every request an API key may make) or admin (write plus the security and audit endpoints).

  • created_atinteger

    Creation time in Unix seconds.

  • expires_atinteger

    Expiry time in Unix seconds (30, 90 or 365 days after creation, as chosen); 0 when the key never expires.

  • revokedinteger

    1 once the key has been deleted (revoked), otherwise 0.

  • statusenum

    active, blocked_leaked (blocked because it may have been leaked), revoked or expired. A blocked key that was also revoked shows blocked_leaked.

  • blocked_atinteger

    When the key was blocked, in Unix seconds; 0 if it is not blocked.

  • blocked_reasonstring

    Why it was blocked, for example found in a public GitHub location https://github.com/…, reported as leaked or used from 3 countries within an hour (SI, US, BR); "" if it is not blocked.

  • blocked_byenum

    What blocked it: github (GitHub secret scanning), report (a public report), behaviour (unusual use) or admin; "" if it is not blocked.

  • replaced_byuuid

    Id of the key that replaced this one; "" if it was not replaced.

  • revoke_atinteger

    For a rotated key: when it stops working and is revoked automatically, in Unix seconds; 0 if nothing is scheduled.

  • allowed_ipsarray<string>

    IP addresses and CIDR ranges the key may be used from. An empty array means any address.

  • last_used_atinteger

    When the key was last used, in Unix seconds; 0 if it was never used. Updated at most once a minute, or sooner when the address changes.

  • last_used_ipstring

    IP address of the last request made with the key; "" if it was never used.

  • keystringmay be absent

    The full secret key. Returned only in the create and rotate responses.

  • replacesuuid

    Id of the old key.

  • old_key_revoke_atinteger

    When the old key stops working, in Unix seconds; 0 when it stopped at once (grace_hours: 0, or a blocked key).

Status codes

  • 201Created. The new key, including the secret key, plus the id of the key it replaces and when that one stops working.
  • 400Bad request. grace_hours is not a whole number from 0 to 72, or the id is not a valid UUID.
  • 401Unauthorized. No signed-in session (unauthorized).
  • 403Forbidden. API keys can never call this endpoint (API keys cannot administer workspaces). A signed-in user who is not an owner or admin gets admin required; a user who is not a member of the workspace gets forbidden.
  • 404Not found. No key with this id in the workspace.
  • 409Conflict. The key was already rotated or replaced (code: "api_key_already_replaced"). Use the key in its replaced_by.