# Tenants and access

Register your customers and decide what each one sees.

GOAT issues a viewer token only for a tenant it knows. A tenant is one of your customers. Its id is your own id for that customer. It is also the value your datasets use to mark which customer each row belongs to, in the dataset's tenant key column.

## The sign-in token these calls need

The calls on this page 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. A sign-in lasts at most 12 hours and cannot be extended.

## Tenant ids

A tenant id follows these rules:

- Letters, digits, `-`, and `_` only. No spaces, dots, or `@`.
- Starts with a letter or digit.
- At most 64 characters.
- Numbers without leading zeros: `7`, not `07`.
- When a dataset's tenant key combines several columns, the id is their values joined by `::`, such as `acme::eu`. Each part follows the rules above, and the whole id is at most 200 characters.

The id must match the values in your tenant key columns exactly. A registered id that matches no rows shows dashboards with no data.

## Register tenants

An install registers tenants by hand, which is the default, or also automatically at the first token request once an Admin turns that on. Both are done through the API. The app has no control yet for registering customers or for turning on automatic registration.

### By hand, one call per tenant

Before your backend asks for a viewer token for a new customer, someone registers the customer once:

```http
POST https://analytics.example.com/v5/admin/tenants
Authorization: Bearer <an admin's or author's own sign-in token>
Content-Type: application/json

{ "tenantId": "acme" }
```

GOAT answers `201 Created`. Until a tenant is registered, a token request for it answers `404 TENANT_UNKNOWN`.

### Automatically, on the first token request

An Admin can switch the install, through the settings API, to register unknown tenants on their own. From then on, when your backend asks for a viewer token for a tenant GOAT does not know, GOAT registers it as active and issues the token. Your backend needs only its API key.

To switch it on, an Admin reads the install's settings, then changes one field. The change sends back the `ETag` the read returned, as `If-Match`. On an install whose settings were never changed, the read returns no `ETag`, and the change is sent without `If-Match`.

```http
GET https://analytics.example.com/v5/admin/settings
Authorization: Bearer <an admin's own sign-in token>
```

```http
PATCH https://analytics.example.com/v5/admin/settings
Authorization: Bearer <an admin's own sign-in token>
If-Match: <the ETag from the GET, if it returned one>
Content-Type: application/json

{ "tenantProvisioning": "AUTO_ON_MINT" }
```

To switch back to registering by hand, send `"HOOK_ONLY"`, the API's name for registering by hand and the default.

The trade-off is that GOAT registers any well-formed id your backend sends with a valid API key. With this on, GOAT no longer checks ids against a list, so your backend alone decides which customer a token is for. These rules follow:

- If your backend sends a wrong id that matches values in your data, tokens for that id read the rows holding it. A typo or another system's id becomes a registered tenant, and it sees the rows of any dataset with no tenant key, which every tenant shares.
- To cut a customer off, suspend it. A deleted tenant is registered again at its next token request.

With automatic registration on, a token request can also answer `422 INVALID_TENANT` for an id GOAT cannot accept.

### Many at once

To register up to 1,000 tenants in one call:

```http
POST https://analytics.example.com/v5/admin/tenants/register
Authorization: Bearer <an admin's or author's own sign-in token>
Content-Type: application/json

{ "tenantIds": ["acme", "globex", "initech"] }
```

GOAT answers `200` with three lists of ids: `created`, `existing` (already registered), and `refused`. Each list keeps the order you sent the ids in, and each refused id comes with its code and message. Sending the same ids again is safe. Send more than 1,000 in batches; a larger request answers `413 REGISTER_TOO_LARGE`.

An Admin can also bring the registered tenants in line with your own customer list, up to 1,000 at a time:

```http
POST https://analytics.example.com/v5/admin/tenants/sync
Authorization: Bearer <an admin's own sign-in token>
Content-Type: application/json

{ "tenants": [{ "tenantId": "acme" }, { "tenantId": "globex" }], "suspendAbsent": false }
```

Each id in your list is registered if it is new, and updated if it is already registered. With `suspendAbsent` set to `true`, registered tenants missing from your list are suspended, never deleted. Build that list from your own records, not from the ids found in your data.

### From the ids in your data

GOAT can list the tenant ids it finds in your datasets' tenant key columns, beside the ones already registered:

```http
GET https://analytics.example.com/v5/admin/tenants?include=discovered
Authorization: Bearer <an admin's or author's own sign-in token>
```

Each item in `items` says whether the id is `registered`, whether it can be registered (`registrable`), and which datasets hold it (`datasets`). To look in fewer datasets, add `collectionId=<id>` or `datasetId=<id>` to the query string. The list reads up to 10,000 values per dataset. The answer's `scope` says when a dataset's values were cut short (`capped`) or could not be read (`failed`). Register the ids you want with the call above. A listed id gets no token until it is registered.

## Suspend, reactivate, or remove a tenant

An Admin suspends a tenant by changing its status:

```http
PATCH https://analytics.example.com/v5/admin/tenants/acme
Authorization: Bearer <an admin's own sign-in token>
Content-Type: application/json

{ "status": "SUSPENDED" }
```

From then on, its token requests answer `403 TENANT_SUSPENDED`, and its open dashboards stop within a minute, showing "This account is suspended. Contact whoever shared this dashboard." Send `"ACTIVE"` to reactivate it.

To offboard a customer, suspend it. An Admin can also delete a tenant with `DELETE /v5/admin/tenants/{id}`. Deleting also removes the tenant's access to dashboards (its grants), and with automatic registration on, the tenant is registered again at its next token request. Delete a tenant only once its rows have left your datasets.

## Access to dashboards

A tenant sees a dashboard when both are true:

- The dashboard is published, and its tenant access is Visible or Customizable. For your viewers, Customizable is the same as Visible.
- The tenant has access to it. A first publish at Visible or Customizable gives every tenant access. A dashboard first published at None needs the "Share with all customers" button, under "Choose who can see it" in Publish & share.

To give one tenant access, keep one out, or give access by a tenant's attributes, see [Grant access to dashboards](grants.md).

## Common problems

| What you see | What to check |
|---|---|
| A token request answers `404 TENANT_UNKNOWN` | The tenant is not registered, or its id breaks the rules above. |
| A registered tenant sees dashboards with no data | Its id does not match the values in the tenant key column exactly. |
| A tenant cannot open a dashboard others can | It is suspended, or it has a `DENY` grant. See [Grant access to dashboards](grants.md). |
| A suspended tenant still sees dashboards for a moment | Suspension reaches open pages within a minute. |
| A token request answers `403 TENANT_SUSPENDED` | The tenant is suspended. Reactivate it. |
| A register call answers `413 REGISTER_TOO_LARGE` | Over 1,000 ids. Send them in batches. |
| A register or create call answers `422 INVALID_TENANT` | The id breaks the rules above. |
| A call to the admin API answers `403 ADMIN_REQUIRED` or `401 SESSION_EXPIRED` | The call needs an Admin, or the sign-in is over 12 hours old. |
| A call to the admin API answers `409 CONFLICT` | The record changed since you read it. Read it again and resend. |
