Viewer Tokens
A Viewer Token is one of the three access-token types in Survanta. It is read-only: it opens a page that shows survey results to a visitor who does not have a Survanta account. The visitor can never submit or edit anything.
Purpose
A Viewer Token lets you share survey results with someone outside your organization in a controlled, read-only way. You choose whether the token covers all permitted surveys or one specific survey, and which viewing capabilities are enabled.
Who Creates It
An authorized tenant user with Tenant.ManageViewerTokens creates a Viewer Token from the dashboard. Platform staff need the matching System permission and selected-tenant context.
What the Visitor Sees
The visitor opens a read-only results page. It shows a table of submitted responses, with columns such as survey, submitted date, status, and answer count. Pagination appears when there are many responses. An export button appears only if export was enabled. If full response details are enabled, each row links to a details page.
What the Visitor Can Do
The visitor can do only what the enabled capabilities allow, and only within the token's scope:
- View submitted responses — read the results table.
- View full response details — open a details page for a single response.
- View answer templates — see the answer templates.
- View own submitted responses — this returns an empty result for an accountless viewer link, because the token does not identify a respondent.
- Export responses — download a JSON export of the responses.
What the Visitor Cannot Do
- Submit a new response or edit any response.
- See data outside the token's scope.
- See surveys or data belonging to any other tenant.
- See dashboard navigation or dashboard screens.
Creation Steps
- Open the Dashboard.
- In the sidebar, open Access Links & Tokens and choose Viewer Tokens.
- Open the Create Viewer Token page.
- Set the Survey scope, choose which capabilities to enable, and set any other optional fields.
- Choose Create.
- On the issued page, use the Copy button to copy the one-time link (or Open to preview it).
- Share the copied link with your intended audience through a safe channel.
Field Guide
| Field | Required | What it does |
|---|---|---|
| Survey scope | Yes | A single-select control: All permitted surveys, or one specific survey. This sets which results the token can show. |
| Name | No | A label to help you recognize the token later in the list. |
| Expires at | Yes | Must be in the future and within ViewerTokenMaxDays; export-enabled tokens use the shorter ViewerExportMaxDays maximum. |
| Passcode | No | A secret code the visitor must enter to open the page. |
| Require passcode | No | A switch that turns passcode entry on for this token. |
| View submitted responses | No | Capability switch: show the responses table. |
| View full response details | No | Capability switch: allow opening a per-response details page. |
| View answer templates | No | Capability switch: show the answer templates. |
| View own submitted responses | No | Capability switch. For an accountless viewer link this returns an empty result, because the token does not identify a respondent. |
| Export responses | No | Capability switch: enable a JSON export of the responses. |
Only enabled capabilities are exposed on the visitor's page.
Expiration
Expires at is mandatory. The service rejects a missing, past, or over-maximum value. An expired token cannot open its results page.
Passcode
If you turn on Require passcode and set a Passcode, the visitor must enter the correct code before the results page opens. A wrong passcode shows a generic "unable to open" message and does not reveal any internal state.
Revoke
You can revoke a Viewer Token at any time from the dashboard. Revoke is a POST action protected by antiforgery. Once revoked, the token can no longer open its results page.
Plan Limit
The number of active, unexpired Viewer Tokens is governed by MaxViewerTokens. A plan downgrade retains the oldest allowed tokens and revokes newer excess tokens; expired tokens do not consume capacity.
One-Time Link Display
The raw link is shown exactly once, on the issued page, right after you create it, with Copy and Open buttons. It is never retrievable later and is never stored in plain form; only a hash is kept. List and detail pages show safe metadata only — name, scope, status, availability window, and usage capacity — never the raw link or its hash. If you lose the link, create a new one and revoke the old one.
Practical Example
You want to give an external client read-only access to permitted results. Create a Viewer Token, set the survey scope (all permitted surveys, or one specific survey), enable View submitted responses and optionally View full response details and Export responses, copy the one-time link, and send it to the client. They can read the results but can never submit or change anything.
Resulting Public Route
https://example.com/viewer/{token}
When full response details are enabled, a single response is reached at:
https://example.com/viewer/{token}/details/{responseId}
When export is enabled, the JSON export is reached at:
https://example.com/viewer/{token}/responses/export
The {token} placeholder is filled in with the value shown once on the issued page.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| "This link has expired" | The Expires at time has passed. | Create a new token and share it. |
| "Unable to open" after entering a code | The passcode is wrong. | Re-check the passcode you shared, or issue a new token. |
| The results page will not open | The token was revoked. | Create a new token if access is still needed. |
| "View own submitted responses" shows nothing | The token does not identify a respondent, so this capability returns an empty result for an accountless link. | Use View submitted responses to show results instead. |
| The scoped survey does not appear | The specific survey the token was scoped to is unavailable. | Re-check the scope, or create a token scoped to an available survey. |
| No export button appears | Export was not enabled on the token. | Create a token with Export responses enabled. |
| "Limit reached" when creating | You have reached MaxViewerTokens. | Revoke a token you no longer need, or review your plan limit. |
| You cannot reach the create page | Your account lacks Tenant.ManageViewerTokens or the matching selected-tenant System permission. |
Ask an authorized administrator to create the token or grant access. |