Apply an edition license

This guide walks you through activating the Enterprise edition on a self-hosted SupaCloud instance. Enterprise is unlocked by supplying a valid HS256 license token and a matching signing secret. The instance is otherwise fail-closed: any missing, expired, or invalid token resolves to the Community edition.

Note

Contact your SupaCloud account representative to obtain an edition license token. The token is a signed JWT; you also receive the corresponding secret that was used to sign it.

Prerequisites

• A running self-hosted SupaCloud instance (see Self-host with Docker Compose).
• The license token string (SUPACLOUD_EDITION_LICENSE).
• The HMAC signing secret used to sign the token (SUPACLOUD_EDITION_SECRET). The secret must be at least 32 bytes long; shorter secrets are rejected at boot and the instance falls back to Community.

Apply the license

1. Set the two environment variables in the location your deployment reads from — .env for Docker Compose, your secrets manager, or OpenBao (supacloud/app — see Secret provisioning):

   Variable	Value
   SUPACLOUD_EDITION_LICENSE	The HS256 JWT license token.
   SUPACLOUD_EDITION_SECRET	The signing secret, ≥ 32 bytes.

   For a Docker Compose deployment add both to your .env:

   SUPACLOUD_EDITION_LICENSE=<your-license-token>
   SUPACLOUD_EDITION_SECRET=<your-signing-secret>

2. Restart the server so the new values are read. The edition is resolved once at startup and cached for the process lifetime:

   docker compose -f docker-compose.yml -f compose.standalone.yml restart server

3. Verify the edition by checking the startup logs for the resolved edition or by navigating to Admin → Features in the operator console. Enterprise features (for example, BYO-OIDC single sign-on) should now be available.

License expiry

The license token carries an exp claim. Once the token expires the instance automatically reverts to Community on the next restart. Renew your license token before the expiry date and restart the server.

How the license is verified

The server reads SUPACLOUD_EDITION_LICENSE and SUPACLOUD_EDITION_SECRET via resolve_secret — env var first, then the OpenBao supacloud/app map when the openbao secret backend is active. It then:

1. Checks that the secret is at least 32 bytes; shorter secrets are refused.
2. Decodes and verifies the token with algorithm HS256.
3. Validates the exp claim (expired tokens are rejected).
4. Checks that the edition claim equals enterprise (case-insensitive).

Any failure — wrong secret, expired token, missing claim, or malformed JWT — silently resolves to Community. No error is surfaced to end-users; a warning is written to the server log.

Developer bypass (non-production only)

On a local development instance you can skip the license token entirely by setting:

MODE=dev
SUPACLOUD_EDITION=enterprise

Development only

The dev bypass is ignored whenever MODE is prod or production. Never set MODE=dev on a production deployment.

Related

• Environment variable reference
• Secret provisioning
• Self-host with Docker Compose