Skip to main content
GET
/
api
/
sso
/
jwt
Authenticate via JWT for embedded Basedash
curl --request GET \
  --url https://charts.basedash.com/api/sso/jwt
"<string>"

​
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: 
{
  "email": "[email protected]",
  "orgId": "org_abc123",
  "firstName": "Jane",
  "lastName": "Doe",
  "role": "MEMBER",
  "exp": 1234567890,
  "iat": 1234567800
}

​
Example implementation

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

// 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: '1h' }
);

​
Security considerations

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

Query Parameters

​
jwt
string
required

JWT token signed with your organization embed secret (HS256)

Response

Redirect to organization dashboard on successful authentication