---
title: "Share a dashboard to a Snowflake role."
method: POST
path: "/v1/dashboards/{id}/role-shares"
tags: ["dashboards"]
---

# Share a dashboard to a Snowflake role.

`POST /v1/dashboards/{id}/role-shares`

## Request

- Base URL: `http://localhost:8080`
- URL: `http://localhost:8080/v1/dashboards/{id}/role-shares`
- Auth: one of:
  - API key in cookie `dvt_session`
  - HTTP bearer

Snowflake-mode only (DVT-1670/DVT-1723): shares the dashboard to a
Snowflake role — any caller who lives-holds that role gains read access.
Requires share:manage on the dashboard (owner or a live dvt_admin; an
owner whose LIVE tier is viewer is refused with 403 — DVT-4721, the owner
needs dvt_editor or dvt_admin). Idempotent: sharing an already-shared role is a no-op. `PUBLIC` (and any
other broadly-held pseudo-role) is rejected with 400 — sharing to PUBLIC
would grant account-wide read, bypassing `visibility: public`. Outside
snowflake mode this endpoint does not exist (404).

DVT-2260 (warn, don't block): the share is always created, but when the
sharer's own live Snowflake role set resolves cleanly and does not contain
the target role, the 201 body carries an advisory `warning` — the role may
be misspelled or absent from the account (in which case the share grants
nobody access), or simply a role the sharer does not hold, which is normal.
The check is best-effort and fails open: no `warning` is returned when no
live caller session is available or the resolve fails, so the absence of a
warning is not proof the role exists.

## Request body

- CreateRoleShareRequest: Request body for POST /v1/dashboards/{id}/role-shares. `snowflakeRole` is folded to upper-case and rejected with 400 if it is empty or a broadly-held pseudo-role such as `PUBLIC` (sharing to PUBLIC would grant account-wide read, bypassing `visibility: public`).
  - `snowflakeRole` string, required: The Snowflake role name to share the dashboard to.

## Response `201`

Role share created (or already existed).

- object
  - `data` DashboardRoleShare, required: A dashboard's share to a Snowflake role (DVT-1670/DVT-1723, snowflake-mode only). Any caller who lives-holds this role (per the engine's CURRENT_AVAILABLE_ROLES()) gains read access to the dashboard.
    - `snowflakeRole` string, required: The Snowflake role name, folded to upper-case.
    - `warning` string: DVT-2260, POST responses only: a non-blocking warning — set when the sharer's own live Snowflake role set resolved successfully and does NOT contain this role. The share is created regardless (warn, don't block): the role may not exist in this account (a typo, which would silently grant nobody access) or may simply belong to someone else, the ordinary case. Omitted when the role was found live-held, or when the resolve was skipped or failed (fail-open — never blocks the create).
  - `meta` Meta, required: Response metadata.
    - `requestId` string, required: Correlates with the X-Request-Id header.
    - `total` integer: Item count, present on collection responses.
    - `nextCursor` string, nullable: Opaque keyset-pagination cursor, present on paginated responses (e.g. GET /v1/dashboards) when more rows exist beyond this page. Pass it back as the `cursor` query param to fetch the next page; absent or null on the last page.
    - `roleResolveDegraded` boolean: Snowflake mode only (DVT-2260), on GET /v1/dashboards: present and true when the caller's live Snowflake role resolution failed or was unavailable — role-shared dashboards may be missing from this page. Omitted (not merely false) whenever resolution succeeded or the role-share arm does not apply (off snowflake mode, an org admin/owner, or off the ingress listener).

## Other responses

- `400`: Malformed request.
- `401`: Missing, invalid, or expired session.
- `403`: The caller's role does not permit this action.
- `404`: Resource does not exist.

---

[API](https://skmtc.dev/dvt/apis/dvt-rest-api.md) · [All operations](https://skmtc.dev/dvt/apis/dvt-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dvt/apis/dvt-rest-api/revisions/00016f504165?raw)