Single Sign-On (SSO) Sub-Account Interface

Overview

This endpoint lets you create sub-accounts via single sign-on (SSO). After a sub-account is created, you can sign it in using the same endpoint.

Users created through this endpoint are sub-accounts under your primary account. Their entitlements stay in sync with the primary account. Aside from how they are created and signed in, their entitlements and settings are the same as sub-accounts you create manually.

Before You Integrate

1. Sign in to SurveyMars with your primary account. On the My Account page, find your appId (Account ID).

2. Contact customer support to enable SSO and receive your Secret Key. Use this key only on your server to compute the sign signature. Do not append it to URLs in plain text or expose it in front-end code.

3. Ensure your system can generate a valid SHA256 signature string on the server and can open the login URL with a GET request from the user’s browser or another trusted environment.

Parameters

Method: GET

Endpoint: https://surveymars.com/app/login/sso/verify?appId=&email=&userName=&roleId=&ts=&returnUrl=&language=&isOnlyLogin=&sign=

Parameter	Description	Required
appId	Company ID. After signing in with your primary account, open My Account; the account ID shown there is the appId you need for integration. The query parameter name must be appId (match this document exactly, including case).	Yes
Secret Key	Developer secret. Contact customer support to have it generated; after it is created, you can view it on My Account. Use it only on your server to compute sign.	No
ts	Unix timestamp: number of seconds since 1970-01-01 00:00:00 UTC. Valid for 60 seconds.	Yes
sign	Cryptographic signature. sign is the lowercase hexadecimal SHA256 digest of the concatenated plaintext, passed as the query parameter sign. If roleId is present in the request, the plaintext is appId + email + userName + roleId + ts + Secret Key. If roleId is omitted (optional field left out), the plaintext must not include a roleId segment: appId + email + userName + ts + Secret Key. Concatenation order and types must match exactly. Secret Key is concatenated only on the server and must not appear in the browser address bar. See Signature calculation rules below. Addendum: The query parameter isOnlyLogin is treated like language and returnUrl: it does not participate in the signature plaintext. When isOnlyLogin=true and userName is omitted from the URL, use an empty string for the userName segment when computing sign (order unchanged: appId + email + empty userName + roleId (if present) + ts + Secret Key). To verify your concatenation, you can paste the plaintext string into a third-party tool (for example Online SHA256 hash) to generate the digest. In production, still compute sign in server-side code and never expose the Secret Key to the browser.	Yes
email	Email address bound to the sub-account. Use a value that is absolutely unique in your integration. Cannot be empty.	Yes
userName	Display name for the sub-account. Maximum 150 characters. Cannot be empty. If the value contains spaces, Chinese characters, or other special characters, URL-encode the parameter (for example, encode spaces as %20). Addendum: When isOnlyLogin=true, userName is optional (sign-in only, no sub-account creation; see isOnlyLogin). When isOnlyLogin=false or the parameter is omitted (defaults to false), userName is required.	Conditional
isOnlyLogin	Whether to sign in to an existing sub-account only, without creating one. Values true / false (lowercase recommended); if omitted, defaults to false. This parameter is not part of the SHA256 signature input. true: Only validates and signs in an existing sub-account for the given email; never creates a new sub-account; userName is optional. If no sub-account exists, the product shows a user does not exist message (wording follows the UI language). false or omitted: userName is required. If a sub-account for that email already exists, the user is signed in; otherwise a sub-account is created and then signed in (first-time creation rules for roleId and other fields still apply).	No
roleId	Role for the new sub-account. Optional. If omitted or empty, defaults to Survey Administrator. Sub-account roles: 1—System Administrator, 2—Survey Administrator, 3—Statistics Viewer, 4—Full Results Viewer, 6—Survey Editor (collaborator). Do not send values outside this list; the API returns an error.	No
returnUrl	Where to redirect after a successful sign-in (relative paths are recommended, e.g. /usercenter, /survey/list). If omitted, users land on My Surveys. URL-encode the path when needed so mobile clients resolve it correctly.	No
language	UI language as an integer. Optional; if omitted, the product default language applies. This parameter does not participate in the sign SHA256 input string above. Value map: 1—Simplified Chinese (zh) 2—English (en) 3—Traditional Chinese (tw) 4—Japanese (ja) 5—Korean (ko) 6—Arabic (ar) 7—French (fr) 8—German (de) 9—Spanish (es) 10—Portuguese (pt) 11—Italian (it) 12—Russian (ru) 13—Thai (th) 14—Turkish (tr) 15—Indonesian (id) 16—Vietnamese (vi) 17—Polish (pl) 18—Dutch (nl) 22—Hebrew (he) 23—Swedish (sv) 27—Danish (da) 28—Finnish (fi) 30—Malay (ms) 31—Norwegian Bokmål (nb) 50—Icelandic (is)	No

How to compute the signature

1. Concatenate the signing fields in fixed order into one string with no separators. If roleId is sent, the order is appId + email + userName + roleId + ts + Secret Key. If roleId is omitted, omit the roleId segment entirely: appId + email + userName + ts + Secret Key. Addendum: When isOnlyLogin=true and userName is omitted from the URL, use an empty string for the userName segment when computing sign; isOnlyLogin itself is never concatenated.

2. Hash the string with SHA256 and use the lowercase hexadecimal digest as sign.

3. Query parameters such as language, returnUrl, and isOnlyLogin do not participate in the signature plaintext; only the fields and order in step 1 apply.

First-time creation vs. later sign-ins

email, roleId, and userName are written only when a sub-account is created for the first time. If a sub-account with that email already exists, later requests do not verify that the new roleId or userName matches what was stored before, and do not update the stored profile with the new values. Invalid signatures or missing required fields can still return signature or parameter errors.

Addendum (isOnlyLogin vs. sign-in / create): When isOnlyLogin=false or omitted: if a sub-account for the email already exists, the user is signed in; if not, a sub-account is created and then signed in (userName and other fields are persisted on first creation). When isOnlyLogin=true: only an existing sub-account may be signed in; nothing is created; if no sub-account exists, the UI reports user does not exist.

FAQ

Q: Why do I see a signature or parameter error?

A: Check that your Secret Key is correct: with roleId, concatenate appId, email, userName, roleId (integer), ts, Secret Key; without roleId, omit the roleId segment (appId, email, userName, ts, Secret Key). With isOnlyLogin=true and no userName in the URL, use an empty userName segment in the plaintext. Confirm ts is within the allowed window and URL encoding does not change the raw concatenated values. Missing appId or an empty email triggers parameter errors; with isOnlyLogin=false (or omitted), an empty userName also triggers parameter errors.

Q: My sub-account is already a Survey Administrator. Why can I still sign in with a wrong roleId?

A: When a sub-account with that email already exists, the system does not validate or update roleId or userName from the current request; those fields mainly affect first-time creation. On first creation you must still send a valid roleId or leave it empty to use the default role.

Q: Why does ts expire so quickly?

A: Production requires the timestamp to be within 60 seconds of server time. Generate ts and sign right before you redirect the user.

Q: What if userName contains spaces or Chinese characters and the call fails?

A: URL-encode your query parameters (encode spaces as %20, and so on). Without encoding, some HTTP clients truncate or mangle the request. That usually looks like a client-side failure, not the server rejecting valid characters.

Q: What is the difference between isOnlyLogin=true and false? Why do I see “user does not exist”?

A: isOnlyLogin=true means sign-in only, no sub-account creation, and userName may be omitted. If there is no sub-account under your primary account for that email, the product shows user does not exist. isOnlyLogin=false or omitted requires userName; an existing email signs in, otherwise a sub-account is created.

Q: How do I delete an SSO-created sub-account in SurveyMars?

A: Sign in with your primary account and delete the sub-account manually on the Sub-accounts page. Removing a user in your own HR or directory system does not delete their SurveyMars sub-account; keep both systems aligned using your own data policies.