API keys

The dev portal at Bloonio → Lisoloo → Developer → API keys is where you manage the single API key tied to your merchant account. This page is a walkthrough of what each control does.

Generate a key

If your account has no key yet, the portal shows an empty state with a Generate API key button. Clicking it:

Issues a new api_key server-side and stores its Argon2id hash.
Returns the cleartext key in the response, once.
Renders a yellow one-time banner with the cleartext, a Copy to clipboard button, and an I have copied it dismiss.

After you dismiss the banner, the cleartext is unrecoverable. The portal only shows the prefix and last 4 characters from that point on — e.g. sk_live_kqz3…oU0i.

Key metadata

Once a key exists, the portal shows a card with six fields:

Field	Source	Notes
Key ID	`identifier`	Stable, public, safe to log. Use this when contacting support.
Key type	`key_type`	Currently always `sms_api`.
Status	`status_lbl`	`ACTIVE`, `SUSPENDED`, `EXPIRED`. Drives the `403` response above.
Environment	`environment`	`sandbox` or `production`, matching the key prefix.
Created	`created_at`	First-issue timestamp.
Last used	`last_used_at`	Updated on every successful request. `Never` if the key has never authenticated a call.

The full key cleartext is never returned a second time — the Your API key display shows only the masked form (sk_live_kqz3…oU0i).

Regenerate

Click Regenerate key to rotate. The portal confirms with a modal — this invalidates the old key immediately. On confirm, a new cleartext appears in the same one-time banner.

Use this when:

You suspect the key was leaked (committed to a public repo, posted in a support ticket, included in a screenshot).
A team member with access to the secret store has left.
It has been ≥12 months since the last rotation (good hygiene, not a hard requirement).

The regenerate operation does not preserve last_used_at, webhook configuration, or any other key metadata — only the cleartext is new. The webhook URL and HTTP Basic credentials persist across rotation.

Configure a webhook on the key

Below the API-key card the portal exposes a Webhook configuration form with three fields:

webhook_url (required to enable webhooks) — the HTTPS URL the gateway POSTs delivery receipts to.
webhook_basic_auth_username (optional) — the username for HTTP Basic auth on outbound calls.
webhook_basic_auth_password (write-only) — the password. The portal never displays it again after save; the webhook_basic_auth_configured: true flag on the API-key row confirms it’s set.

See Webhooks → Configuration for the full flow and event payloads.

Status states

The status field reflects the backend EApplicationKeysStatus enum. Only allowed keys authenticate; everything else returns 403.

Status	Auth result	What it means	What you do
`allowed`	✓ passes	Key is live and verified.	Nothing — normal state.
`pending_validation`	`403`	Key created but not yet activated by Bloonio.	Contact your account manager to activate.
`suspended`	`403`	Manually paused (billing, compliance, abuse review).	Contact your account manager.
`revoqued`	`403`	Marked as revoked.	Regenerate if you still need the integration.
`locked`	`403`	Temporarily locked (typically by automated risk controls).	Contact support.
`expired`	`403`	Hard expiry passed.	Regenerate.
`rejected`	`403`	Application rejected during onboarding.	Contact your account manager.

In addition, keys with soft_deleted: true or a non-null revoked_at timestamp are filtered out at the database level and surface as a generic 401 (the middleware deliberately doesn’t differentiate so that an attacker can’t tell whether a guess hit a deleted row).

Security checklist

The key lives in a server-side environment variable or secrets manager, never in client code.
.env is gitignored.
CI/CD masks the value in logs.
Webhook receivers verify HTTP Basic credentials match the configured pair (see Webhooks → Configuration).
On suspected leak, rotate before revoking — the portal does this atomically with Regenerate.