Tokens API

Whenever a user accesses an Embeddable dashboard in your app, you should fetch a security token from our Tokens API. This token applies row-level security (and more) to their dashboard session.

Example: Fetch a Token

Important: Always call this server-side—never from client code, to avoid exposing your API key.

fetch('https://api.<region>.embeddable.com/api/v1/security-token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': `Bearer ${apiKey}` // Keep your API key secure
  },
  body: JSON.stringify({
    embeddableId: "<dashboard-id>", //the id of the dashboard you want to load
    savedVersion: "production", // or "development" or "staging", etc.
    expiryInSeconds: 60 * 60 * 24 * 7, // token expiry (e.g. 1 week)
    securityContext: { // any context you want to provide to the SQL data models
      userId: '9sZSJ9LHsiYXR0cmlidXRlIjoiZ2VvaXBf',
      regions: ['us-east', 'eu-west']
    },
    user: 'sina@embeddable.com', // unique key representing current user
    dashboardState: 'team1-dashboard7', // optional key used by "custom canvas" functionality to store dashboard state
    environment: 'default', // each environment defines which databases to connect to
    roles: ["manager"] // any access-policy roles to grant this user i.e. manager, default etc.
    })
  })
})
  .then((resp) => resp.json())
  .then(({ token }) => {
    // 'token' is the JWT your web component needs
    console.log(token);
  });

Response:

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJzZWN1cml0eVRva2VuSWQiOiI1OGE1NGYwMi0xNTJmLTQxMjgtYWZmZC0zMDhhYzI0NTE5ZGQiLCJpYXQiOjE3MDczMTU1NDUsImV4cCI6MTcwNzkyMDM0NX0.lnovN0xTMCjLcxGTIfzFD9cYRIAZjn6S7sew-ih11lM"
}

You would then use this token in your <em-beddable> element, as explained in Embedding an Embeddable.

Learn more about region here.

Parameters

embeddableId is the id of the Embeddable dashboard that you want to load. Click 'save version' or 'publish' on your Embeddable dashboard to get the id.
savedVersion this is the saved version of the Embeddable dashboard that you want to load. Available options include:
- 'production' (default) - the saved version published with the 'Production' tag. This will be used by default if savedVersion is omitted.
- 'staging' - the saved version published with the 'Staging' tag
- 'development' - the saved version published with the 'Development' tag
- 'v3' (or v11, etc.) - the saved version with the given version number.

securityContext is an arbitrary JSON object included in your token request. Embeddable passes it to your data models, allowing you to enforce row/table/schema-level security. For example:

name: Orders
sql: >
    SELECT user_id, created_at
    FROM public.orders
    WHERE user_id = '{ COMPILE_CONTEXT.securityContext.userId }'
    
    {% if COMPILE_CONTEXT.securityContext.regions %}
        AND region IN {{ list(COMPILE_CONTEXT.securityContext.regions) }}
    {% endif %}

roles grants the user one or more access policy roles. The roles you include determine which cube models, views, and rows the user can see across dashboards and data playground. If you don’t pass any roles, Embeddable assigns the default role. Refer to Access Policies for details on how roles drive visibility.
user is a unique identifier for the current user. It enables Embeddable to store (anonymous) session metadata against each user automatically so that customisations / preferences applied by the user to their Embeddable dashboard will automatically be remembered for their next session.
environment optionally specifies which environment to retrieve data from. Until you're ready to define environments, omit this parameter for now (by default, “default” is used). Environments let you achieve things like:
- single-tenancy (AKA database-level security), where each of your customers has their data in a different database.
- different database connections for prod, qa, testing, etc.
- micro service architecture, where your data is spread across multiple databases.
expiryInSeconds is the number of seconds until the token expires. The default is 7 days (60 * 60 * 24 * 7). Tokens are standard JWTs, and contain iat and exp when decoded. On your front-end, you can keep track of the token expiry and refresh it as needed with a call to the Embeddable Tokens API, without needing to reload the page.
dashboardState is only needed if you are using Custom Canvas. We basically store a custom canvas layout (per embeddableId) for each unique value of dashboardState that you pass to the Tokens API. So all you have to do is generate some unique string id (e.g. 'dashboard-12') every time you want a fresh new custom canvas and pass that to dashboardState. Then next time they want to see that custom canvas again, just pass the same unique id ('dashboard-12') to dashboardState and Embeddable will automatically display the latest state of that custom canvas.

💡

Note that dashboardState is per embeddableId, so if you want different custom canvas states per environment too (dev vs qa vs prod) then make sure to include the environment name as a prefix or suffix of the dashboardState.

Testing Security Contexts

If you’re relying on securityContext in your data models, you’ll want to test them in Embeddable’s no-code builder. You can easily do this by creating presets.

Embedding dashboards Saved versions