WAPI Keys

WAPI Keys provide key-based authentication for protected WAPI endpoints as an alternative to OAuth bearer tokens. They are available exclusively to verified WiPay BUSINESS accounts (KYC 3).

Key Format

wapi_{environment}_{kid}_{secret}

Example: wapi_live_a1b2c3d4e5f6g7h8i9_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

The environment segment is determined by the platform the key is created on — production platforms produce live keys, sandbox platforms produce test keys. A live key cannot authenticate against a sandbox endpoint and vice versa.

Creating a WAPI Key

1. Log into your verified WiPay BUSINESS Account.
2. Navigate to the Developer page (profile menu → Developer).
3. Open the WAPI Keys tab.
4. Click Create WAPI Key.
5. Fill in the creation form:

6. On success, the plaintext key is displayed once. Copy it immediately — it cannot be retrieved again.

WiPay stores only an HMAC-SHA256 hash of the key. If the plaintext is lost, create a new key and revoke the old one.

Using a WAPI Key

Send the plaintext key in the X-WAPI-Key header on any protected WAPI request:

X-WAPI-Key: wapi_live_a1b2c3d4e5f6g7h8i9_0123456789abcdef...

Do not send both X-WAPI-Key and Authorization: Bearer on the same request. Requests that send both, send neither, or use an invalid, expired, or revoked credential are rejected with 401 Unauthorized.

After authentication, the endpoint checks the key's scopes against the route requirement. Parent scopes satisfy child scope requirements.

Managing WAPI Keys

Editing a Key

Only name and allowed CIDRs can be changed after creation. Scopes and expiry are immutable — to change them, create a new key and revoke the old one.

Revoking a Key

1. On the WAPI Keys tab, locate the key to revoke.
2. Click Revoke and confirm.

Revocation is immediate and permanent — a revoked key cannot be restored. Any request using a revoked key returns 401 Unauthorized.

Key Rotation

There is no regenerate function. To rotate a key:

1. Create a new key with the desired scopes and settings.
2. Update your application to use the new key.
3. Revoke the old key.

Key Reference Display

Since the full key is shown only once, the Developer page displays a masked reference for each key: the kid segment followed by the last 4 characters of the secret (e.g., a1b2c3d4e5f6g7h8i9...cdef).

Authentication Flow

When a request arrives with X-WAPI-Key:

1. The key is parsed into environment, kid, and secret.
2. The environment must match the current platform (live or test).
3. The key record is located by kid and environment.
4. The full key is verified against the stored HMAC-SHA256 hash.
5. The key must not be revoked or expired.
6. If allowed_cidrs are configured, the request IP must match at least one range.
7. Scopes are loaded and checked against the endpoint requirement.

Requirements

• Account type: Verified WiPay BUSINESS account (KYC 3).
• Authentication alternative: PERSONAL accounts must use the OAuth bearer-token flow.
• Scope reference: See Scopes for the full list of available scopes and their hierarchy.