How Auto Login works

Learn how the Genuin SDK turns a token from your backend into a signed-in member, from the first request to session refresh.

Auto Login is for apps that already know who their user is. Your app hands the SDK a token that your backend issued. Genuin verifies the token with your backend, finds or creates the member, and starts a session. The member never sees a Genuin login screen.

This page explains the mechanism. For the choice between Auto Login, single sign-on, and Genuin's own sign-in sheet, see Choose how members sign in to the Genuin SDK. For the calls on each platform, see the SDK guides linked under See also.

Systems involved

The original diagram also showed a "device middleware" and a "data warehouse". Neither takes part in sign-in. The device id in the request is generated by the SDK, and analytics run after sign-in through Mixpanel and your event callbacks.

The sequence

1. The member signs in to your app, and your backend issues a token that your verification endpoint will recognise later.
2. Your app passes the token to the SDK: GenuinSDK.ssoLogin(context, token, params) on Android, GenuinSDK.shared.ssoLogin(ssoToken:params:) on iOS, or the token option of window.genuin.init() on the web.
3. The SDK compares the token with the one it stored last time: a repeat ends here with no network call, and a new token first clears the previous member's data.
4. The SDK sends POST /api/v4/sso/autologin with the token, your brand id, the device type, the login source, a device id, and any profile parameters you passed.
5. Genuin loads your brand's configuration and calls your verification URL with the token, or, in bypass mode, takes the email or phone number from the request itself.
6. Genuin looks the member up by the returned phone number first and then by email, and creates a passwordless identity when there's no match; no one-time code is sent.
7. Genuin creates the session and fills the member profile with the name, nickname, and profile image it has; brand guidelines are accepted when your brand is set to auto-accept them.
8. If you sent a brand_user_identity, Genuin stores it against the member for your own reports.
9. The response carries the member profile in data and the session in the gn-access-token and gn-refresh-token headers. The SDK stores them with your token, logs a KS Signed Up or KS Logged In event, and reloads its views as the member.

data.is_user_signedup tells the SDK which event to log: true on the member's first sign-in, false afterwards.

The token contract

What your backend issues

Any string. The SDK sends it unchanged, and Genuin doesn't parse it, with two exceptions. A token in email format is lowercased, and in bypass mode a token in email or phone format becomes the member's identity. A session id, an opaque random string, or a JWT all work, as long as your verification endpoint can turn it into a profile.

The SDK keeps the token on the device so that it can skip the network call when your app passes the same token again. Issue tokens you can revoke, and rotate them when the user signs out of your app.

What Genuin calls to verify it

Genuin reads your brand's Auto Login configuration and calls your verification URL with the token. The configuration names where the token goes (a header, the body, a cookie, the query string, or the path) and maps your response fields to Genuin's fixed keys:

A response with neither mobile nor email can't be matched to a member, and the request fails with the login error described under What happens on failure.

Bypass mode. With bypass set on your brand's Auto Login configuration, Genuin skips the verification call. The email, mobile, name, nickname, profile_image, and brand_user_identity fields of the request become the profile, and a token in email or phone format becomes the identity. When the request has neither a name nor a nickname, the part of the email before @ becomes the name.

Verification through your identity provider. When your brand has single sign-on configured and Auto Login isn't enabled, Genuin treats the token as an OAuth access token from your provider. It calls your provider's user info endpoint with the token and applies the user info mapping from your SSO settings. An app that already holds a provider access token can sign the member in this way without showing the Continue with <your brand> button.

What the SDK sends

With a verification URL, the profile parameters fill in what your response leaves empty on the member's first sign-in. In bypass mode they are the identity. nickname is used if it's free; otherwise Genuin generates one.

How sessions are kept and refreshed

The response headers gn-access-token and gn-refresh-token carry the session. An access token stays valid for 14 days in production and 3 hours in QA; a refresh token for 100 days in production and 24 hours in QA. The SDKs refresh at POST /api/v4/auth/session/refresh on their own.

The body's data object holds the member: user_id, name, nickname, email, phone, profile_image, bio, birthday, brand_id, device_uuid, is_user_signedup, is_username_generated, onboarding_topics, brand_guidelines, and ks_cb_request_status. The Web SDK keeps it in localStorage together with your token; the mobile SDKs keep it in app storage (EncryptedSharedPreferences on Android, UserDefaults on iOS 2.1.5).

When the refresh fails, the Web SDK runs Auto Login again with the stored token and signs the member back in without a call from your code. On iOS a failed refresh signs the member out of the SDK; pass the token again with ssoLogin.

Passing the same token again is free: the SDK answers from storage. Passing a different token signs the previous member out locally and starts a new request. To sign out, call GenuinSDK.ssoLogout() on Android or iOS, which calls POST /api/v4/auth/signout and clears local data, or window.genuin.logout() on the web, which clears the stored session on the page.

What happens on failure

Genuin answers every request with the same shape: an HTTP status, a string code, a message, and a data object. The SDKs surface the result as a boolean.

On failure the SDK logs a Sign In Failed analytics event with the server message as the reason and keeps showing content as a guest. The Genuin sign-in sheet then opens on the next action that needs an account, unless your app registered a sign-in callback. See Choose how members sign in to the Genuin SDK.

Where the brand configures it

Auto Login has no screen in Brand Control Center. The Genuin team enables it on your brand record and stores the verification URL, the token placement, the field mapping, and the bypass flag. Send them:

1. The verification URL and the HTTP method it expects.
2. Where the token goes: header name, body field, cookie name, query parameter, or path segment.
3. The name of each field in your response for userid, email, emailVerified, and mobile, plus any optional field you want mapped.
4. Whether you want bypass mode, and whether new members accept your brand guidelines automatically.

Single sign-on, by contrast, is self-serve under Settings > Setup Single Sign On (SSO). Its user info mapping doubles as the mapping Genuin applies when it verifies an Auto Login token at your identity provider.

Limitations

• One identity per device: Passing a different token signs the previous member out of the SDK before the new request.
• Email or phone required: A verification response with neither can't become a member. Member accounts are keyed by phone number or email. A member who later signs in on your community site with a one-time code for the same email lands in the same account.
• One error code: Every verification problem returns code 5031. Diagnose with your endpoint's logs rather than the Genuin response.
• No test mode: Use the QA environment with a brand configured for QA. Tokens and configurations aren't shared between environments.
• No Brand Control Center screen: Changes to the verification URL or mapping go through the Genuin team.
• Sign-out isn't propagated: ssoLogout ends the Genuin session only. Your app's own session is untouched, and Genuin never calls your backend on sign-out.

See also

• Choose how members sign in to the Genuin SDK
• Set up single sign-on with your identity provider
• Integrate the Genuin Android SDK
• iOS SDK 2.0 — integrate your brand community in iOS apps
• Generate an access token with the Authentication API
• Handle API errors