BBline-X

Setup Keys

A setup key is the credential an agent presents to enroll into your mesh. When an agent enrolls with a valid key, management registers the device, assigns it a mesh IP, and issues a JWT for the REST API.

The default key

Every fresh control plane seeds a default setup key, BLINEX-DEFAULT-KEY, valid for one year. It exists so you can get a mesh running immediately. The default value can be overridden at deploy time with the BLINEX_DEFAULT_KEY environment variable in your .env.

Replace the default key before production. Anyone who knows it and can reach your control plane can join the mesh. Create purpose-specific keys and revoke the default.

Creating a key

From the dashboard

Open the Setup Keys page, click Create key, give it a name and (optionally) an expiry, and copy the generated value. The plaintext key is shown once.

From the API

curl -X POST https://your-host:8080/api/setup-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-runners","expires_in_days":30}'

See the REST API reference for the full setup-keys endpoints.

Using a key

Pass the key to the agent via environment variable:

sudo BLINEX_SETUP_KEY=blx_xxxxxxxx blinex-agent

or via flag:

sudo blinex-agent --setup-key blx_xxxxxxxx

You can also store it in /etc/blinex/agent.json under the setup_key field. See the Agent docs for the full config file.

Lifecycle

  • Expiry. Keys can be created with an expiry date. After expiry, the key can no longer enroll new devices.
  • Revocation. Delete a key from the dashboard or via DELETE /api/setup-keys/:id. Already-enrolled devices keep their own JWTs and stay on the mesh — revoking a key only stops new enrollments.

Best practices

  • Create one key per purpose (CI runners, laptops, prod servers).
  • Set an expiry on keys you only need for a short onboarding window.
  • Revoke the seeded default key once your real keys are in place.
  • Treat setup keys as secrets — store them in a secrets manager, not in version control.