SSO Contacts Interface

This article explains how to sign a contact in with an email address or a third-party user ID. It uses the same appId and Secret Key as the sub-account SSO interface, but the URL, signature fields, and landing page are different. Create sub-accounts and set roles with the sub-account SSO interface.


Overview

Send the contact email or third-party user ID. SurveyMars checks the signature and signs that contact in. After a successful sign-in:

- A valid surveyId opens that survey's response page. It takes priority over returnUrl.

- If surveyId is omitted or invalid, SurveyMars opens returnUrl. This applies to both sub-accounts and other contacts, including the contact page.

- If returnUrl is omitted, a sub-account opens the survey list. Any other contact opens the contact home page.


Use Cases

- Your system already has a contact email or third-party user ID, and you want password-free access to SurveyMars.

- Pass surveyId to open a survey for response right after sign-in.

- Both sub-accounts and other contacts can follow returnUrl, including the contact page.


Before You Start

1. Sign in with the main account and copy appId (account ID) from My Account.

2. Ask support to enable the Secret Key. Use the key only on your server. Do not put it in the URL or in front-end code.

3. Build the SHA256 signature on your server, then open the login link with GET.


appId on My Account



Request

Method: GET

URL: https://surveymars.com/app/login/contact/verify?appId=&email=&thirdUserId=&ts=&language=&returnUrl=&surveyId=&sign=


Parameter Required Description
appId Yes Main account ID. Use the same appId as the sub-account SSO interface.
email Conditional Contact email. Provide email or thirdUserId. email is required when the main account has not enabled "Allow empty contact email".
thirdUserId Conditional Third-party user ID. Provide email or thirdUserId. If both are sent, verification ignores thirdUserId, but the value still joins the signature.
language No Language of the prompt and survey. Does not join the signature.
returnUrl No Page to open after sign-in. Applies to sub-accounts and other contacts, including the contact page. Does not join the signature. If the address contains & or ?, URL-encode the entire returnUrl once.
surveyId No Survey ID. Does not join the signature. A valid value opens that survey's response page and takes priority over returnUrl. An invalid value opens returnUrl.
ts Yes Unix timestamp in seconds since 1970-01-01 00:00:00 (UTC). Valid for 60 seconds. The ts in the URL must match the ts used in the signature. Generate it immediately before opening the link.
sign Yes Signature. sign is the lowercase hexadecimal SHA256 of the joined plain text: appId + email + thirdUserId + ts + Secret Key. Keep this order. The Secret Key is joined only on the server and must not appear in the browser address bar. See Signature below.


Signature

How to calculate the signature


1. Join the signed fields in this exact order, with no separator: appId + email + thirdUserId + ts + Secret Key. Use an empty string for an omitted email or thirdUserId. Do not drop that segment, and do not use a placeholder. The Secret Key is joined only on the server and must not appear in the browser address bar.


2. Calculate SHA256 of that string. Use the lowercase hexadecimal result as sign.


3. language, returnUrl, and surveyId do not join the signature. Use only the fields and order in step 1.


4. ts is the number of seconds since 1970-01-01 00:00:00 (UTC). It is valid for 60 seconds. Generate ts and sign immediately before the user is redirected. The ts in the URL must match the ts used in the signature. URL encoding must not change the original values used in the join.


5. To check the join, paste the plain text into a third-party SHA256 tool (for example, LZL online SHA256). In production, generate sign on your server. Do not expose the Secret Key to the browser.


6. Do not reuse a sub-account SSO signature. That interface uses appId, email, userName, roleId, and ts. This interface does not use userName or roleId.



Email and thirdUserId

1. Provide at least one of email and thirdUserId.

2. If both are sent, verification uses email and ignores thirdUserId. thirdUserId must still join the signature with its original value, and it can remain in the URL.

3. email is required when the main account has not enabled "Allow empty contact email".


Where the Contact Lands

1. A valid surveyId opens that survey's response page. It takes priority over returnUrl.

2. If surveyId is omitted or invalid, SurveyMars opens returnUrl. This is no longer limited to sub-accounts. Other contacts can follow it too, including the contact page.

3. If returnUrl is omitted, a sub-account opens the survey list. Any other contact opens the contact home page.


Encoding returnUrl

If returnUrl contains & or ?, URL-encode the entire returnUrl once before you place it in the login link. Do not encode only part of it, and do not encode it twice. Without this, & and ? are treated as separators of the login link, and the server cannot read the full address.

For example, the original address https://surveymars.com/app/contacts?tab=1&id=2 is written once encoded as:

returnUrl=https%3A%2F%2Fsurveymars.com%2Fapp%2Fcontacts%3Ftab%3D1%26id%3D2

returnUrl does not join the signature, so encoding does not change sign.



Important Notes

- Use the Secret Key only on the server. Do not put it in the browser address bar.

- This interface signs contacts in. It does not create sub-accounts or set sub-account roles.

- Encode characters such as @ in email when you place them in the URL. The signature still uses the original value before encoding.

- surveyId is optional and does not join the signature. A valid value opens the response page. An invalid value opens returnUrl.

- If returnUrl contains & or ?, URL-encode the entire address once.


FAQs

Q: How is this different from sub-account SSO?
A: Sub-account SSO uses /app/login/sso/verify to create or sign in a sub-account. Contact sign-in uses /app/login/contact/verify with an email or third-party user ID. The signature fields are different. Do not reuse sign.


Q: Can I send thirdUserId without email?
A: Yes, if the main account has enabled "Allow empty contact email". Otherwise email is still required. Use an empty string for the omitted field in the signature.


Q: I sent both email and thirdUserId. Why did sign-in use the email?
A: When both are sent, verification ignores thirdUserId and identifies the contact by email. thirdUserId still joins the signature.


Q: Can a contact who is not a sub-account follow returnUrl?
A: Yes. returnUrl is no longer limited to sub-accounts. Other contacts can follow it too, including the contact page. A valid surveyId still opens that survey's response page first.


Q: If I send both surveyId and returnUrl, which page opens?
A: A valid surveyId opens that survey's response page and takes priority over returnUrl. If surveyId is invalid or omitted, SurveyMars opens returnUrl.


Q: returnUrl contains & or ?. Why is the address incomplete?
A: URL-encode the entire returnUrl once. For example, encode ? as %3F and & as %26. Do not encode only part of the value, and do not encode it twice.


Q: Why does signature verification fail?
A: Check the Secret Key. Join appId, email, thirdUserId, ts, and the Secret Key in that order. Use an empty string for an omitted email or thirdUserId. Confirm that ts is still within 60 seconds, and that URL encoding did not change the original values. Do not include language, returnUrl, or surveyId.


Q: Why does ts expire so quickly?
A: In production, the timestamp must be within 60 seconds of the server time. Generate ts and sign immediately before the user is redirected.

How helpful was this article?