Embed in your product
Grant access to dashboards
Give one tenant access to a dashboard, keep one out, or give access by attribute.
Publishing a dashboard at Visible or Customizable for the first time gives every tenant access to it. This page covers changing that: giving one tenant access, keeping one tenant out, and giving access by a tenant's attributes. All of it is done through the API, since the app has no control for it yet.
Before you start
These calls take a person's own sign-in token, an admin's or an author's, not an API key. The app does not yet give a way to get that token, and these docs do not yet cover it. See Tenants and access.
How access works
Access is a list of grants. Each grant is for one dashboard and one tenant, or for every tenant ("*"), at the level VIEW or DENY. A grant for one tenant wins over the grant for every tenant.
Grant or deny one tenant
To give one tenant access:
POST https://analytics.example.com/v5/admin/grants
Authorization: Bearer <an admin's or author's own sign-in token>
Content-Type: application/json
{ "tenantId": "acme", "dashboardId": "dash_abc", "level": "VIEW" }
GOAT answers 201 with the grant and its grantId.
To keep one tenant out of a dashboard every other tenant sees, give it a DENY grant:
{ "tenantId": "globex", "dashboardId": "dash_abc", "level": "DENY" }
To take access back, delete the grant with DELETE /v5/admin/grants/{grantId}. GET /v5/admin/grants lists them.
Changes reach viewers within a minute.
Grant by tenant attributes
A tenant can carry up to 20 attributes, such as "plan": "enterprise", set when it is created or with a PATCH. A grant can name an attribute instead of a tenant:
{ "dashboardId": "dash_abc", "attributeSelector": { "key": "plan", "value": "enterprise" } }
GOAT answers with the selector, a standing rule, and the grants it made from it. It gives the dashboard to every tenant whose attribute matches. Tenants that gain or lose the attribute later gain or lose the dashboard with it.
To withdraw an attribute grant, an Admin deletes the rule with DELETE /v5/admin/grant-selectors/{id}, which also removes the grants it made. Deleting those grants one by one leaves the rule in place, and it adds them again the next time a tenant matches. GET /v5/admin/grant-selectors lists the rules; an install holds up to 100.
Attribute grants give access only; they cannot deny. To keep one matching tenant out, give it a DENY grant first, before the attribute grant.
Errors
| Status and code | What it means |
|---|---|
422 INVALID_GRANT | The tenant id, dashboard id, or level is not valid. Level is VIEW or DENY. |
409 GRANT_SLOT_CONFLICT | The grant clashes with one already held for that tenant and dashboard, such as a DENY sent after an attribute grant gave the tenant access. |
422 SELECTOR_CAP | The install already has 100 attribute grants. |
422 INVALID_SELECTOR | An attribute grant's selector or level is not valid. |
422 FILTER_DOMAIN_REQUIRED | This is the dashboard's first grant, and a filter on it needs its choices set first. Set them, then grant again. |
422 SENSITIVE_ACK_REQUIRED | This is the dashboard's first grant, and a filter on it uses a PII or Sensitive column. Resend with "sensitiveAttachAck": true to confirm. |
The grant calls refuse a field they do not know with their own 422 code, so a misspelt field name reads as an invalid grant. The full list is on Errors.
Common problems
| What you see | What to check |
|---|---|
| A dashboard published at None and then raised to Visible shows to no one | Choose Share with all customers in Publish & share, or grant tenants one by one. |
| A tenant cannot open a dashboard others can | It has a DENY grant. |
| A tenant you removed from an attribute grant can see the dashboard again | The rule is still in place. Delete the rule, not its grants. |