Access Tokens — Security and Troubleshooting
This page explains the common hash-only, tenant-scoped validation model and the lifecycle differences among Public Survey Links, Portal Tokens, and Viewer Tokens.
Token Secrecy
The raw link for any token is shown exactly once, on the issued page, right after you create it, with Copy and Open buttons.
- The raw link is never retrievable later. If you did not copy it, you must create a new token.
- The raw value is never stored in plain form. Only a hash of it is kept.
- List and detail pages show safe metadata only — name, scope, status, availability window, and usage capacity. They never show the raw link or its hash.
Because the raw value cannot be recovered, treat every issued link like a secret. Share it only through a safe channel, and revoke it if it may have been exposed.
Expiration
Expiry is optional for SingleSurvey and TenantActiveSurveys. It is mandatory for ResponseViewer: normal viewer tokens are bounded by ViewerTokenMaxDays, and export-enabled viewers by the shorter ViewerExportMaxDays. A Public Survey Link may also have a start time. Unavailable credentials fail closed.
Passcode
You can require a passcode on any token. Only its SHA-256 hash is stored and comparison is constant-time. Public surfaces should avoid revealing token state; the mobile resolver does distinguish passcode-required/invalid as HTTP 401 and unavailable tokens as HTTP 410.
Revoke
You can revoke any token at any time from the dashboard. Revoke is a POST action protected by antiforgery. Once revoked, the token can no longer open its public page. Revoking one token does not affect any other token.
Scope
Every token is scoped to the tenant that created it, and it never exposes another tenant's data:
- A Public Survey Link opens exactly one survey.
- A Portal Token covers the tenant's currently active, published surveys only.
- A Viewer Token covers all permitted surveys, or one specific survey if you scoped it that way.
No token ever exposes data outside its scope.
Read-Only Viewer Behavior
A Viewer Token is strictly read-only. It shows results according to the capabilities you enabled, and the visitor can never submit or edit anything. The "View own submitted responses" capability returns an empty result for an accountless viewer link, because the token does not identify a respondent.
Plan Limits
Each token type has its own plan limit, enforced on the server:
| Token type | Plan limit |
|---|---|
| Public Survey Link | MaxPublicSurveyLinks |
| Portal Token | MaxPortalTokens |
| Viewer Token | MaxViewerTokens |
Creation enforces the limit in a quota transaction. Plan-downgrade reconciliation retains the oldest allowed active tokens and revokes newer excess tokens, so existing tokens are not guaranteed to survive a reduced limit. Expired tokens do not consume capacity.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| "This link has expired" | The token's expiry time has passed. | Create a new token and share it. |
| The page will not open | The token was revoked. | Create a new token if access is still needed. |
| "Unable to open" after entering a code | The passcode is wrong. | Re-check the passcode you shared, or issue a new token. |
| A portal shows no surveys | The tenant has no currently active, published surveys. | Publish or activate at least one survey. |
| "Limit reached" when creating | You reached the plan limit for that token type. | Revoke a token you no longer need, or review your plan limit. |
| You cannot reach the create page | Your dashboard account lacks the permission to create tokens. | Ask a Tenant Admin to create the token or grant access. |
| A viewer's scoped survey is unavailable | The specific survey the Viewer Token was scoped to is not available. | Re-check the scope, or create a token scoped to an available survey. |