JWT Security

Overview

JSON Web Tokens (JWTs) authenticate supported mobile/API calls for eligible tenant users. The official login contract is POST /api/mobile/auth/login; retired researcher-only login contracts are not supported.

What Is a JWT in Survanta?

A JWT is a compact, digitally signed credential sent as Authorization: Bearer <jwt>. Survanta issues it after an eligible tenant user signs in with email and password.

The token contains claims that describe:

• Who the token was issued to (uid and name-identifier claims)
• Role claims available at issuance; tenant context and active membership are resolved and enforced by protected policies rather than trusted from arbitrary client input
• When the token expires

JWT Scope

JWT authentication is used by mobile surveys, submissions, tasks, notifications, complaints, lookups, configuration, and other API controllers that explicitly select the bearer scheme. This means:

• A JWT cannot be used to sign in to the Survanta tenant dashboard.
• A JWT cannot be used to sign in to the Survanta public website.
• A JWT cannot be used to impersonate a Platform Admin or access platform-level tools.
• A JWT grants access only where endpoint policy, active same-tenant user, access channel, subscription, and required permission checks also pass.

There is no mechanism to exchange a JWT for broader permissions than those originally issued.

Token Expiry

JWTs have an expiry time embedded in the token itself. Once a token has expired:

• The API will reject any request made with the expired token.
• The researcher must re-authenticate to obtain a new token.

This expiry mechanism limits the window of risk if a token is ever intercepted or leaked. An expired token is useless.

Best Practices for Tenant Users

• Do not share your JWT with anyone. It is a personal credential tied to your identity.
• Do not store a JWT in an insecure location such as a plain text file, a public code repository, or a browser's local storage in a shared environment.
• Re-authenticate promptly after a token expires rather than storing long-lived copies.
• If a token is exposed, remove it from the client, protect any registered device token, and contact the administrator. The current backend exposes no per-JWT revocation endpoint.

Token Revocation

The current JWT is self-contained and validated for signature, issuer, audience, lifetime, and claims. No JWT blacklist, logout, or individual-token revocation endpoint is exposed. Administrators can disable account access, and protected tenant policies may then deny operations, but this is not the same as revoking a specific token.

• A tenant user leaves the organization
• A device is lost or stolen
• A token is suspected to have been exposed

Clients must not claim immediate server-side revocation. The deterministic token boundary is its expiry; endpoint account/policy checks can independently deny an otherwise valid token.

Frequently Asked Questions

Does Survanta use refresh tokens? No refresh-token endpoint is exposed. The login response includes expiresAtUtc; after expiry, the tenant user must sign in again.

Can a JWT be used to access another tenant's data? No. A JWT is issued for a specific tenant and can only access data within that tenant. Tenant isolation applies to JWT-authenticated requests just as it does to all other access methods.

What should I do if my JWT appears in a log or error message? Treat the token as compromised, remove it from logs and client storage where possible, contact the administrator to review/disable account access if needed, and sign in again after remediation. A fresh token does not itself revoke the leaked token.