Skip to main content

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 codeWhat it means
422 INVALID_GRANTThe tenant id, dashboard id, or level is not valid. Level is VIEW or DENY.
409 GRANT_SLOT_CONFLICTThe 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_CAPThe install already has 100 attribute grants.
422 INVALID_SELECTORAn attribute grant's selector or level is not valid.
422 FILTER_DOMAIN_REQUIREDThis is the dashboard's first grant, and a filter on it needs its choices set first. Set them, then grant again.
422 SENSITIVE_ACK_REQUIREDThis 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 seeWhat to check
A dashboard published at None and then raised to Visible shows to no oneChoose Share with all customers in Publish & share, or grant tenants one by one.
A tenant cannot open a dashboard others canIt has a DENY grant.
A tenant you removed from an attribute grant can see the dashboard againThe rule is still in place. Delete the rule, not its grants.
GOAT documentation

Type to search.