> ## 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
  - name: Dashboards
    description: Manage dashboards and their tabs
  - name: Charts
    description: Manage charts and their SQL queries
  - name: Chats
    description: >-
      Chat with the Basedash AI agent about your data. Start a chat by sending a
      message, then continue the conversation with follow-up messages. The
      assistant responds asynchronously: pass the `wait` query parameter to
      receive the finished response in the same request, or poll the assistant
      message (or stream its events) after an HTTP 202. Chats created through
      the API are not shown in the Basedash app.
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: []

````