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.
- If the contact is a sub-account, SurveyMars opens returnUrl. If returnUrl is omitted, it opens the survey list.
- If the contact is not a sub-account, SurveyMars ignores returnUrl and 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.
- A sub-account contact lands on returnUrl. Other contacts skip returnUrl and land on the contact home page.
Before You Start
1. Sign in with the main account and copy appId 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.
Request
Method: GET
| Parameter | Required | Description |
| appId | Yes | Main account ID. Use the same appId as the sub-account SSO interface. |
| Conditional | Contact email. Provide email or thirdUserId, or both. email is required when the main account has not allowed an empty contact email. | |
| thirdUserId | Conditional | Third-party user ID. Provide email or thirdUserId, or both. If both are sent, verification uses email only. thirdUserId still joins the signature. |
| language | No | Language of prompt messages. It does not join the signature. |
| returnUrl | No | Page to open after a sub-account signs in. SurveyMars follows it for a sub-account contact and ignores it otherwise. It does not join the signature. |
| ts | Yes | Seconds since 1970-01-01 00:00:00 UTC. It stays valid for 60 seconds. The ts in the URL must match the ts used in the signature. Generate it when the user is about to open the link. |
| sign | Yes | Signature. sign is the lowercase hexadecimal SHA256 of the joined plaintext: appId + email + thirdUserId + ts + Secret Key. The order must match exactly. The Secret Key is joined only on the server and must not appear in the browser address bar. See Build the Signature below. |
Build the Signature
Signature rules
1. Join the signing fields in a fixed order with no separator: appId + email + thirdUserId + ts + Secret Key. If email or thirdUserId is omitted, use an empty string in that position. Do not drop the field, and do not replace it with a placeholder. The Secret Key is joined only on the server and must not appear in the browser address bar.
2. Hash that string with SHA256 and use the lowercase hexadecimal value as sign.
3. language and returnUrl 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 stays valid for 60 seconds. Generate ts and sign when the user is about to open the link, and use the same ts in the URL. URL encoding must not change the original values used in the signature.
5. To check the joined string, paste it into a SHA256 tool such as 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 string uses appId, email, userName, roleId, and ts. This interface does not use userName or roleId.
For example：
http://surveymars.com/app/login/contact/verify?appId=TTeEB8&[email protected]&ts=1790760357&language=2&returnUrl=https://surveymars.com/app/usercenter&sign=26c0c7d9da5e38c61d4aeecb223336d7a259cad0b75c8ff912855421fd832a4e
Email and Third-Party User ID
1. Send at least one of email and thirdUserId.
2. If you send both, verification uses email and ignores thirdUserId. Keep the original thirdUserId in the signature, and you may keep it in the URL.
3. If the main account has not allowed an empty contact email, email is required.
4. If this setting is off, contact support to turn on "Allow empty contact email." After it is on, you can add a contact without an email.
Where the Contact Lands
1. Sub-account contact: SurveyMars opens returnUrl. If returnUrl is omitted, it opens the survey list.
2. Other contacts: SurveyMars ignores returnUrl and opens the contact home page.
Important Notes
- Keep the Secret Key on your server. Do not place it in the browser address bar.
- This interface signs in a contact. It does not create a sub-account or set a sub-account role.
- URL-encode characters such as @ in email. Sign the original value, not the encoded value.
FAQs
How is this different from sub-account SSO?
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.
Can I send only thirdUserId?
Yes, if the main account allows an empty contact email. Otherwise email is required. Use an empty string for the omitted field in the signature.
I sent both email and thirdUserId. Why does sign-in use the email?
When both are present, verification ignores thirdUserId and matches the contact by email. thirdUserId still joins the signature.
Why did a contact who is not a sub-account skip returnUrl?
returnUrl applies only when the contact is a sub-account. Otherwise SurveyMars ignores it and opens the contact home page.
Why does signature verification fail?
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 or returnUrl.
Why does ts expire so quickly?
In production, ts must be within 60 seconds of the server time. Generate ts and sign when the user is about to open the link.
