Skip to main content

API keys

Every server-to-server integration with Wink authenticates with an API key sent in a header:

X-API-Key: wk_live_<40 hex characters>

Properties​

  • Shown once. The full key appears exactly once, at creation. Wink stores only a cryptographic hash and cannot recover the plaintext. If a key is lost, create a new one and revoke the old.

  • Scoped. A key carries one or more scopes — the capabilities it grants. Current scopes:

    ScopeGrants
    call_eventsPOSTing to the call-events webhook
    recommendation_engineCalling the recommendation engine

    A request outside a key's scopes is refused with 401 even when the key itself is valid. More scopes will appear as Wink's API surface grows.

  • Organization-bound. Keys belong to your organization and only authenticate on your organization's API host. A key leaked from one org is useless against another.

  • Environment-bound. Live keys are prefixed wk_live_; test keys (wk_test_) are only accepted by Wink's staging hosts and are physically refused in production. Ask for a test key while building.

  • Revocable, immediately. Revocation takes effect on the next request. Revoked keys keep appearing in your key list as history.

Managing keys​

Organization owners manage keys in the Wink app under Org Settings → API Keys: create a key with a label and scopes, copy the plaintext from the one-time dialog, and revoke keys that are no longer needed. The page also shows each key's last-used time — a key that has never been used, or one used seconds ago, is visible at a glance.

Handling guidance​

  • Store keys in your platform's secret store or credential facility — never in source control, scripts, tickets, or email.
  • Send keys over HTTPS only, always in the X-API-Key header — never in a URL, where proxies and access logs capture them.
  • Use separate keys for separate senders (production dialler, test rig, CI) so one can be revoked without taking down the others.
  • Treat a suspected leak as an incident: revoke the key in Org Settings (or ask the Wink team) and mint a replacement. Rejected calls show up to the caller as 401.