> ## 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
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",
  "exp": 1234567890,
  "iat": 1234567800
}
```

## Example implementation

```html
<iframe 
  src="https://charts.basedash.com/api/sso/jwt?jwt=YOUR_JWT_TOKEN"
  width="100%"
  height="600"
  frameborder="0"
/>
```

```javascript
// Server-side JWT generation (Node.js example)
import jwt from 'jsonwebtoken';

const token = jwt.sign(
  {
    email: user.email,
    orgId: 'org_abc123',
    firstName: user.firstName,
    lastName: user.lastName,
    role: 'MEMBER',
  },
  process.env.BASEDASH_EMBED_JWT_SECRET,
  { expiresIn: '10m' }
);
```

## Security considerations

* **Keep your JWT secret secure** - Never expose it in client-side code
* **Use short expiration times** - JWTs should expire within minutes
* **Configure allowed origins** - Restrict embedding to your domains only
* **Generate JWTs server-side** - Never generate JWTs in the browser


## OpenAPI

````yaml https://charts.basedash.com/api/public/openapi get /api/sso/jwt
openapi: 3.1.0
info:
  title: Basedash Public API
  version: 0.0.0
  description: >-
    API for programmatic access to Basedash features. Use API keys for
    authentication.
  contact:
    name: Basedash Support
    url: https://basedash.com
    email: support@basedash.com
servers:
  - url: https://charts.basedash.com
    description: Production
security: []
tags:
  - name: Organizations
    description: Manage organizations
  - name: Groups
    description: Manage organization groups and memberships
  - name: Data Sources
    description: Manage database connections and data sources
  - name: MCP servers
    description: Manage MCP server data sources
  - name: Insights
    description: Manage generated insights
  - name: Automations
    description: Manage automations and automation runs
  - name: Skills
    description: Manage organization skills
  - name: Definitions
    description: Manage reusable SQL definitions
paths:
  /api/sso/jwt:
    get:
      tags:
        - Embedding
      summary: JWT authentication
      description: >-
        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.
      parameters:
        - schema:
            type: string
            description: JWT token signed with your organization embed secret (HS256)
          required: true
          description: JWT token signed with your organization embed secret (HS256)
          name: jwt
          in: query
      responses:
        '302':
          description: Redirect to organization dashboard on successful authentication
          headers:
            Location:
              schema:
                type: string
                description: URL to the organization dashboard
              required: true
              description: URL to the organization dashboard
            Set-Cookie:
              schema:
                type: string
                description: Session cookie
              required: true
              description: Session cookie
        '400':
          description: Bad request - Missing JWT, invalid format, or invalid claims
          content:
            text/html:
              schema:
                type: string
                description: HTML error page
        '401':
          description: Unauthorized - JWT signature verification failed or expired
          content:
            text/html:
              schema:
                type: string
                description: HTML error page
        '403':
          description: Forbidden - Embedding not enabled or request from disallowed origin
          content:
            text/html:
              schema:
                type: string
                description: HTML error page
        '404':
          description: Not found - Organization not found
          content:
            text/html:
              schema:
                type: string
                description: HTML error page
        '500':
          description: Internal server error
          content:
            text/html:
              schema:
                type: string
                description: HTML error page
      security: []

````