# 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](tenants-and-access.md#the-sign-in-token-these-calls-need).

## 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:

```http
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:

```json
{ "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:

```json
{ "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](../reference/errors.md#tenants-grants-and-settings).

## 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. |
