Embedding with access views
Use the Juicebox API to create access views that embed apps with per-user data permissions.
An access view is a URL generated through the Juicebox API that gives a user access to a specific app with specific settings — without requiring them to sign in to Juicebox. Access views are designed to be embedded in iframes on your website.
With access views, you can control what data each user sees (data permissions), what selections are pre-set, whether the Juicebox header and footer are visible, and how many times the link can be used.
How it works
Authenticate with the Juicebox API using a client admin account to get a Bearer token.
Create an access view by POSTing to the API with the app slug, user email, and any desired settings (data permissions, selections, display options).
The API returns an access view object that includes a
urlfield.Load that URL in an iframe on your page.
Each access view URL is typically short-lived and limited-use. You generate a fresh one each time a user needs to see the app.
Step 1: Authenticate
The Juicebox API uses JWT Bearer token authentication. You'll need a Juicebox user account with the Admin role that is set up for password login. To get a token, POST those credentials to the auth endpoint:
POST https://your-workspace.myjuicebox.io/api/v2/auth/
Content-Type: application/json
{
"username": "[email protected]",
"password": "your-password"
}The response includes a token field. Use this token in subsequent requests:
Here's how to set a password for API access. If you need help setting up an Admin account for API access, reach out to us.
Tokens expire after a period of time. You can refresh a token by POSTing to /api/v2/auth/refresh/ with the current token, or verify a token with /api/v2/auth/verify/.
Step 2: Create an access view
To create an access view, POST to the access views endpoint:
The only always-required field is app_slug. The user_email field is required if the app's access is set to "Sign-in required." All other fields are optional.
Access view fields
app_slug
string
Required. The slug of the app to display.
user_email
string
The email address of an existing Juicebox user who will view the app. Required if the app's access is set to "Sign-in required."
selections
object
Pre-sets filter selections in the app. Keys use the format slice_slug:ingredient_id. See Selections below.
show_header
boolean
Whether to show the Juicebox app header. Default: true.
show_footer
boolean
Whether to show the Juicebox app footer. Default: true.
allowed_uses_cnt
integer
How many times the URL can be loaded. 0 = unlimited. Default: 0.
expires_at
datetime
When the access view expires (ISO 8601 format). null = no expiration.
is_active
boolean
Whether the access view can be used. Default: true.
stack_slug
string
An optional stack slug. If set, the app opens to this specific stack / page.
Data permissions
Data permissions control what rows of data the viewer can see. They work by applying filters to every database query the app makes. Here's a brief example:
In this example, the viewer only sees rows where the region column is "Northeast" or "Southeast" AND the status column is "active."
For full details on data permission syntax — including ingredient vs. raw column references, filter operators, and per-app permissions — see Limiting what data users can see.
If the access view includes data_permissions, they override the user account's data permissions entirely (they do not merge). If the access view has no data_permissions, the user account's data permissions apply.
Selections
Selections pre-set the filter state of the app when it loads. Each key in the selections object uses the format slice_slug:ingredient_id, where slice_slug is the slug of the slice (e.g., Filters1) and ingredient_id is the id of the ingredient being filtered. The value is a list of selected values.
In this example, the app opens with two filters pre-set on the Filters1 slice: region set to "Northeast" and "Southeast", and year set to "2025".
Selections determine what the user initially sees in the app's filters. Data permissions determine what data is available. A user can change their selections, but they can never see data outside their data permissions.
Shortcut: one-time-use access views
If you just need a quick, one-time-use access view without custom data permissions or selections, you can use the shortcut endpoint:
This creates an access view with allowed_uses_cnt: 1 that expires after 60 seconds. It's equivalent to POSTing to the access views endpoint with minimal settings.
Step 3: Get the response
The response includes the same fields plus several read-only fields:
The url field is what you embed in your iframe.
Step 4: Embed the `url` in an iframe
Take the url from the access view response and load it in an iframe:
Since access view URLs are typically short-lived, you should generate a new access view each time a user loads your page and inject the URL into the iframe src dynamically.
Common patterns
Per-user embedding
A common pattern is to create an access view each time a user visits your site:
The user logs in to your application.
You look up the user's role or organization.
You call the Juicebox API to create an access view with data permissions matching that user's access level.
You render the page with the access view URL in an iframe.
For example, a school district portal might create access views where each school administrator only sees data for their school:
Shared organizational account
Access views don't require individual user accounts. You can use a single email to represent an organization, and multiple people can use access views associated with that email:
In this pattern, the email identifies the organization rather than an individual person.
API reference
For the complete API specification — including all endpoints, request/response schemas, filtering, pagination, and rate limits — see the interactive API documentation:
Last updated
Was this helpful?