Retrieving Security Tokens

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.<your-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
    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: 'prod' // each environment defines which databases to connect to
    })
  })
})
  .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.

Parameters

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 %}

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.
dashboardState holds the state of the dashboard based on the end-user’s interactions within Embeddable’s Custom Canvas.
environment optionally specifies which which environment to retrieve data from. By default, “default” is used. This lets 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.

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 Configuring environments