Skip to content

API keys

Update a key’s IP allowlist

Replaces the key’s allowed_ips and returns the key. Send an empty array to allow any address again. Only the allowlist can be changed: for another name or scope, create a new key. Recorded in the audit log as api_key.updated.

PATCH/api/v1/keys/{id}
  • 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
  • allowed_ipsarray<string>required

    IP addresses (203.0.113.10, 2001:db8::1) and CIDR ranges (198.51.100.0/24) the key may be used from. Requests from any other address get 403 with code: "ip_not_allowed". An empty array (or leaving it out) allows any address.

    Constraints
    At most 20 entries.
    Example
    ["203.0.113.10"]

Response

200 OKapplication/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 (365 days after creation).

  • revokedinteger

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

  • 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.

Status codes

  • 200OK. The key with its new allowed_ips. The secret is not included.
  • 400Bad request. allowed_ips entry 2 is not a valid IP address or CIDR range, allowed_ips can hold at most 20 entries, send allowed_ips (a list of IP addresses or CIDR ranges) or invalid key id.
  • 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 active key with this id in the workspace (a revoked key cannot be changed).
  • 500Server error. The key could not be updated.