API Keys

API Keys allows admins to generate authentication credentials for external systems to access the Kiwire REST API programmatically — without requiring admin login credentials. Keys are stored as SHA-256 hashes and support IP allowlisting and per-key rate limiting.

'alt' => 'Dashboard overview', 'caption' => 'The default Kiwire dashboard layout', 'screenshot' => true, 'class' => '', ]) Drop images into: public/assets/img/docs/{page}/{filename} --}}

Image not uploaded yet public/assets/img/docs/api-keys/overview.png

What API Keys Are For

Use API keys when an external system — an integration script, a third-party application, a mobile app backend, or an automation pipeline — needs to read or write Kiwire data without a human admin logging in. Examples:

• A PMS (Property Management System) provisioning WiFi accounts when guests check in
• A billing system querying bandwidth usage for invoicing
• An HR system syncing employee accounts
• A custom dashboard fetching user counts and session stats

Security Features

• SHA-256 hashing — keys are stored as one-way hashes. The plaintext key is shown only once at creation. If the key is lost, it must be regenerated.
• IP allowlist — restrict which source IP addresses can use the key. Requests from unlisted IPs receive 403 Forbidden. Leave blank to allow any IP.
• Rate limiting — configurable requests-per-minute cap per key. Exceeded requests return 429 Too Many Requests with X-RateLimit-Limit and X-RateLimit-Remaining headers.
• Expiry — optional expiry date. Expired keys are automatically rejected.
• Scope — each key can be limited to specific API endpoints, following the principle of least privilege.

Key Fields

Field	Description
name	Descriptive label for the key (e.g., "PMS Integration – Main Hotel").
key_prefix	The first 8 characters of the generated key, shown in the grid to identify which key is which. The rest of the key is hashed and never displayed again.
permissions	Which API endpoints or resource types the key is authorised to access.
allowed_ips	JSON array of IP addresses or CIDR ranges permitted to use this key. Empty means any IP is allowed.
rate_limit	Maximum API requests per minute. Set to 0 for no limit.
last_used_at	Timestamp of the most recent successful API request using this key.
expires_at	Optional expiry date. After this date, requests with this key return 401 Unauthorized.
is_active	Enable/disable the key without deleting it. Inactive keys are rejected immediately.

Creating a Key

1. Click Add API Key and fill in the name, permissions, IP allowlist, rate limit, and optional expiry.
2. Save. The full plaintext key is displayed once in a modal.
3. Copy the key immediately and store it securely (e.g., in a secrets manager or environment variable). It cannot be retrieved again.
4. If the key is lost, delete it and create a new one.

Using the Key

Send the key in the HTTP request to the Kiwire API. Two methods are supported:

• Authorization header (recommended): Authorization: Bearer <your-api-key>
• Custom header: X-API-Key: <your-api-key>

Revocation

To immediately block a key: toggle its is_active switch to off, or delete it. Both actions take effect on the next API request. The AuthenticateApiRequest middleware validates the key on every request.

Required Permissions

view-api-keys · create-api-keys · update-api-keys · delete-api-keys