Securing Game Access with JWT Authentication

JWT Authentication lets you securely transmit player information to your Drimify experience and control who can access it. Instead of passing player data in plain query parameters — which anyone can forge — your system issues a signed JSON Web Token (JWT). Drimify verifies the signature using your shared secret, so player identity claims can be trusted without any server-to-server callback.

This is ideal for loyalty programs, member portals, and any scenario where the game is embedded in an authenticated environment and you need to know reliably who is playing.

How it works

1. You create a JWT Configuration in your Drimify account (algorithm + secret).
2. You enable JWT Authentication on your app and select that configuration.
3. Your system generates a signed token containing the player's information and passes it when opening the game.
4. Drimify verifies the token's signature and expiry, reads the mapped claims, and lets the player in. Invalid or missing tokens are blocked with a customisable error screen.

Step 1 — Create a JWT Configuration

Go to My Account → JWT Configurations (just below Integrations) and click to add a new configuration:

• Name: A label for your own reference.
• Algorithm: The signing algorithm your system uses. Supported: HS256, HS384, HS512 (HMAC, shared secret) and ES256, ES384 (ECDSA).
• Secret: The shared secret used to verify the token signature. For security, HMAC secrets must meet a minimum length: 32 characters for HS256, 48 for HS384, 64 for HS512. The secret is masked after saving.
• Workspaces: Select which workspaces can use this configuration. An app can only use configurations available in its workspace.

Field mapping (claim names)

By default, Drimify reads standard claim names from your token. If your token issuer uses different claim names (e.g. user_email instead of email), use the field mapping section to map each of your token's claim names to the corresponding Drimify game parameter.

Field mapping works as an allowlist: only the fields you configure are read from the token. Each Drimify field can be mapped once (no duplicates).

Step 2 — Enable JWT Authentication on your app

In your app editor, open the Settings step and turn on Enable JWT Authentication. Then:

• Select the JWT configuration to use (only configurations available in the app's workspace are listed — if none exist, a link takes you to JWT Configurations).
• Optionally set a custom error title and description, shown to players when access is denied (missing or invalid token).

Step 3 — Pass the token when opening the game

Your system can deliver the token in three ways (if several are present, this is also the order of precedence):

1. Bearer header — Authorization: Bearer <token> — recommended for production, as the token never appears in URLs, logs, or browser history.
2. Query string — https://your-game-url?jwt=<token> — convenient for testing, but tokens in URLs can leak via logs and browser history.
3. POST data — a jwt=<token> form field.

Token requirements

• The token must be signed with the algorithm and secret defined in your JWT Configuration.
• Include an exp (expiry) claim and keep token lifetimes short — expired tokens are rejected. A small clock-skew tolerance is applied, so minor clock differences between servers won't cause failures.
• Claims should contain the player fields you mapped in the configuration (e.g. email, unique ID, username, phone number).

Example payload

{
  "sub": "user-123",
  "email": "player@example.com",
  "iat": 1753257600,
  "exp": 1753261200
}

You can generate test tokens at jwt.io by pasting your secret in the signature verification field.

Security behaviour to be aware of

• Query parameters no longer override player data. When JWT Authentication is enabled, player information comes exclusively from the verified token — plain query-string values are ignored. This prevents anyone from bypassing the token by editing the URL.
• Participation limits are enforced from the token. If your app limits plays by email or phone number, the corresponding claim must be present in the token; otherwise access is denied. Invalid email or phone values are also rejected, so limits cannot be bypassed with malformed data.
• Configurations in use cannot be deleted. A JWT Configuration that is still referenced by an app must be unassigned before it can be removed.
• Keep your secret safe. Anyone holding the secret can issue valid tokens. If a secret is compromised, update it in the configuration — note that this immediately invalidates all tokens signed with the old secret.

Troubleshooting

• Players see the access error screen: Check that the token is signed with the right algorithm and secret, has not expired, and is passed via one of the three supported methods.
• Player data not appearing: Verify your field mapping — only mapped claims are read from the token.
• Configuration not listed in the app settings: Make sure the configuration is enabled for the app's workspace.

Updated on: 23/07/2026