Skip to main content

Access Protection

Gate your chatbot behind a secret URL key so that only authorized users can access it — even before the login page.

Overview​

Access Protection adds a layer before authentication. Without a valid key in the URL, visitors are completely blocked from seeing any part of the chatbot, including the login page.

This is useful when you want to:

  • Share a chatbot only with specific partners or customers via a secret link
  • Embed a chatbot in your app and restrict access to your users
  • Prevent the general public from discovering or accessing the chatbot
MethodURL ParameterUse Case
App Key?appkey=<key>Simple link protection — share with team, embed in wiki
JWT Token?token=<jwt>Expiring access links, backend-generated tokens with identity
graph LR
    A[Visit Chatbot] --> B{Has key/token?}
    B -->|No| C[Access Restricted]
    B -->|Yes| D{Key valid?}
    D -->|No| C
    D -->|Yes| E{Auth required?}
    E -->|Yes| F[Login Page]
    E -->|No| G[Chat Interface]
    F --> G
info

Access Protection works alongside Authentication and SSO. When both are enabled, the user first needs a valid key to get past the gate, then logs in normally.

Setting Up Access Protection​

Step 1: Enable Access Protection​

  1. Open your chatbot in the WizChat dashboard
  2. Go to the Edit page
  3. Scroll to the Access Protection section (under Authentication)
  4. Toggle the switch to Active

Step 2: Create an App Key​

  1. In the Access Protection section, enter a label for your key (e.g., "Production", "Partner A")
  2. Click "+ Generate Key"
  3. Copy the generated key immediately
warning

The full key is only shown once. Store it securely — you won't be able to retrieve it later.

  1. Click "Save Access Protection Settings"

Step 3: Share the Protected URL​

Append the key to your chatbot URL:

https://your-chatbot.wizchat.app/?appkey=YOUR_KEY_HERE

Users visiting this URL will have access. Users visiting without the key will see an "Access Restricted" page.

App Keys​

App keys are static secrets appended to the chatbot URL. They're the simplest way to restrict access.

How It Works​

  1. You generate a key in the dashboard
  2. The key is hashed (SHA-256) and stored — the original key is never saved
  3. When a user visits with ?appkey=<key>, the server hashes the provided key and compares it against stored hashes
  4. If the hash matches, access is granted and the key is removed from the URL bar
  5. The validated session is stored in the browser tab (sessionStorage) so the user doesn't need to re-validate on every page

Managing Keys​

You can have up to 10 active keys per chatbot. This lets you issue different keys to different partners and revoke them individually.

Generate a Key​

  1. Enter a descriptive label
  2. Click "+ Generate Key"
  3. Copy and store the key securely

Import an Existing Key​

If you already have a key you'd like to use:

  1. Check "Import an existing key instead"
  2. Paste your key (minimum 16 characters)
  3. Enter a label
  4. Click "+ Add Key"

Revoke a Key​

  1. Find the key in the Active Keys list
  2. Click the trash icon
  3. Confirm revocation in the dialog

Revoked keys stop working immediately. Users with that key will be blocked on their next visit.

JWT Token Support​

For more advanced scenarios, you can accept signed JWT tokens instead of static keys. This allows:

  • Expiring links — tokens that automatically stop working after a set time
  • User identity — extract an email address from the token for tracking
  • Backend integration — your server generates tokens for authenticated users

Configure JWT​

  1. In the Access Protection section, enable JWT Token Support
  2. Enter your JWT signing secret (used to verify token signatures)
  3. Optionally set the email claim field (default: email) to extract user identity from the token
  4. Click "Save Access Protection Settings"
warning

The JWT secret is encrypted and stored securely. It is only shown once when you enter it.

Supported Algorithm​

Currently only HS256 (HMAC-SHA256) is supported.

Generating JWT Tokens​

Generate tokens from your backend using the secret you configured. The token should include:

{
  "exp": 1700000000,
  "email": "user@company.com"
}
ClaimRequiredDescription
expRecommendedExpiration time (Unix timestamp). Expired tokens are rejected.
emailOptionalUser's email address. Extracted if the email claim is configured.

Example using Node.js:

const jwt = require('jsonwebtoken');

const token = jwt.sign(
  { email: 'user@company.com' },
  'YOUR_JWT_SECRET',
  { expiresIn: '24h' }
);

const chatbotUrl = `https://your-chatbot.wizchat.app/?token=${token}`;

Using JWT Tokens​

Append the token to the chatbot URL:

https://your-chatbot.wizchat.app/?token=eyJhbGciOiJIUzI1NiIs...

Embedding with Access Protection​

When embedding a chatbot with access protection, include the key or token in the iframe URL:

<iframe
  src="https://your-chatbot.wizchat.app/embed/CHATBOT_ID?appkey=YOUR_KEY"
  width="400"
  height="600"
/>

For JWT-based embedding, generate a token server-side and inject it into the iframe URL dynamically.

Session Behavior​

  • Validated access is stored in sessionStorage (scoped to the browser tab)
  • Closing the tab clears the session — the user needs the key again
  • Navigating within the chatbot does not require re-validation
  • The key/token is automatically removed from the URL bar after validation

Security​

  • Keys are validated server-side — hashes are never exposed to the client
  • SHA-256 hashing with timing-safe comparison prevents timing attacks
  • JWT secrets are encrypted at rest using AES-256
  • The key is removed from the browser's URL bar after validation to prevent leaking via browser history or referrer headers

Troubleshooting​

Users still see the chatbot without a key​

  • Verify Access Protection is toggled Active and you clicked "Save Access Protection Settings"
  • Ensure at least one active key exists — access protection requires both the toggle and an active key
  • Wait a few minutes for the configuration to propagate, or visit the chatbot in an incognito window

Valid key shows "Access Restricted"​

  • Double-check you're using the full key, not just the prefix shown in the dashboard
  • Verify the key hasn't been revoked
  • Ensure there are no extra spaces or characters in the URL parameter

JWT token rejected​

  • Verify the token hasn't expired (exp claim)
  • Ensure the signing secret matches what you configured in the dashboard
  • Confirm the algorithm is HS256
  • Check that the token is properly URL-encoded in the ?token= parameter