> ## Documentation Index > Fetch the complete documentation index at: https://basedash.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # JWT authentication > Validates a JWT signed by the embedding application and creates a Basedash session for the user specified in the JWT claims. On success, redirects to the organization dashboard. ## When to use This endpoint is used for **full app embedding** - embedding the entire Basedash application within your own product via an iframe. This allows your users to access Basedash dashboards without leaving your application or managing separate Basedash credentials. ## How it works 1. Your server generates a JWT containing user information, signed with your organization's embed JWT secret 2. You set the iframe `src` to this endpoint with the JWT as a query parameter 3. Basedash validates the JWT signature against your organization's secret 4. If valid, Basedash creates or updates the user account and establishes a session restricted to that organization 5. The user is redirected to your organization's dashboard inside the iframe ## Setup requirements Before using this endpoint, you must: 1. **Enable embedding** for your organization via the API or Basedash settings 2. **Store the embed JWT secret** returned when creating/updating your organization - this is used to sign your JWTs 3. **Configure allowed origins** (recommended) to restrict which domains can embed your Basedash organization ## JWT structure Sign your JWT using the HS256 algorithm with your organization's `jwtSecret`. The JWT payload should contain: ```json { "email": "user@example.com", "orgId": "org_abc123", "firstName": "Jane", "lastName": "Doe", "role": "MEMBER", "groups": ["Billing", "Program A"], "exp": 1234567890, "iat": 1234567800 } ``` The optional `role` claim accepts `ADMIN`, `MEMBER`, or `VIEWER`. When supplied, it is the source of truth for the active membership on every login. Omit it to preserve an active membership's role; new or reactivated memberships without a role claim default to `MEMBER`. `VIEWER` is read-only. ## Groups The optional `groups` claim lists the names of existing Basedash groups the user belongs to. Use it to scope dashboards, chats, data sources and row-level security to groups you manage from your application. When supplied, it is applied on every login: | Situation | Result | | - | - | | A name matches a group the user isn't in | The user is added to the group | | The claim no longer names a group this claim added the user to | The user is removed from that group | | The user was added to a group in Basedash, through the API or by SCIM | Never removed by the claim | | `groups` is `[]` | Removes every membership the claim added | | `groups` is omitted | Group memberships are left unchanged | * Names match case-insensitively, ignoring leading and trailing spaces. * Groups are never created. Create them first with `POST /organizations/{orgId}/groups`, and give them access before users log in. * A name that matches no group, matches more than one group, or names a SCIM-managed group is skipped. So is the whole claim when it lists more than 100 distinct names. The login still succeeds. Each login that changes memberships or skips a name records a `group.login_token_synced` audit event listing the groups added and removed and every skipped name with its reason (`unknown`, `ambiguous`, `scim_managed` or `invalid_name`). * Audit logs require the Enterprise plan. On Enterprise, find these events under **Settings → Audit logs**, or query them with an administrator API key: `GET /organizations/{orgId}/audit-logs?action=group.login_token_synced`. On other plans, compare the names you send with `GET /organizations/{orgId}/groups`. * If an admin removes a membership the claim added, the next login adds it back. To revoke access, remove the group from the claim. To revoke it immediately as well, also remove the membership in Basedash or through the API. * On data sources with row-level security, group names are passed to your policies, so adding a group can widen the data a user sees. ## Example implementation ```html