User authentication in Wristband follows the Backend Server Integration Pattern, where your backend server handles all authentication with Wristband and your frontend communicates only with your backend server. Wristband provides two types of SDKs for this pattern:

Backend server auth SDKs handle the login, callback, and logout flows with Wristband, manage the application session, refresh access tokens, and protect your routes and APIs.
Frontend SDKs initialize the user's auth state in the browser by calling your backend server, and redirect users to your backend server's Login and Logout Endpoints.

The pages in this section cover how these SDKs behave at each stage of user authentication.

What the SDKs Handle

The SDKs take care of the protocol-level work so your application only needs to wire up endpoints and decide what happens at a few key points.

Area	Handled by the SDKs	Handled by Your Application
Configuration	Fetching missing configuration values from Wristband through auto-configuration	Providing the client ID, client secret, and Wristband application vanity domain
Login	Resolving the tenant domain, creating the Login State Cookie, and building the redirect to Wristband	Exposing the Login Endpoint and returning the SDK's redirect
Callback	Validating the Login State Cookie, exchanging the authorization code for tokens, retrieving userinfo, and validating the return URL	Exposing the Callback Endpoint, creating the session from the callback data, and choosing where to send the user after login
Logout	Revoking the refresh token and building the redirect to Wristband's Logout Endpoint	Exposing the Logout Endpoint and destroying the application session
Sessions	Storing the session in an encrypted cookie, and building the Session and Token Endpoint responses	Initializing the session from the callback data, saving and destroying it, and deciding what additional data to store
Token Refresh	Refreshing expired access tokens using the refresh token	Handling failed refreshes, typically by sending the user back to login
Route Protection	Validating the session or Bearer token on each request through auth middleware	Choosing which routes and APIs require authentication
CSRF Protection	Generating CSRF tokens and validating them in the auth middleware, in SDKs that support it	Enabling CSRF protection and sending the CSRF token in a request header from the frontend
Frontend	Loading the session from the Session Endpoint, caching access tokens from the Token Endpoint, and building login and logout redirects	Wrapping the app with the frontend SDK, providing the endpoint URLs, and handling 401 responses from your APIs

The User Authentication Lifecycle

User authentication moves through the following stages, from logging in to logging out:

Login: The frontend redirects the user to your Login Endpoint. The backend server auth SDK resolves the tenant, creates the Login State Cookie, and redirects the user to Wristband to authenticate.
Callback: After authentication, Wristband redirects the user to your Callback Endpoint. The backend server auth SDK completes the login and returns the tokens and user data.
Session: Your Callback Endpoint initializes the application session from the callback data, and the SDK stores it, typically in an encrypted session cookie.
Authenticated Requests: The frontend SDK calls your Session Endpoint to load the user's auth state. The auth middleware validates the session on each protected request, refreshes expired access tokens, and validates CSRF tokens if CSRF protection is enabled.
Logout: The frontend redirects the user to your Logout Endpoint. Your application destroys the session, and the backend server auth SDK revokes the refresh token and redirects the user to Wristband to end the Wristband auth session.

For a protocol-level explanation of this flow, see Login Workflow.

In This Section

Backend SDK Configuration: How to configure the backend server auth SDKs, including auto-configuration.
Auth Endpoints: The endpoints your backend server exposes and what the SDKs do in each.
Session Management: How the SDKs manage encrypted cookie-based sessions.
Login: How the SDKs start the login flow and resolve the tenant domain.
Callback: How the SDKs complete the login flow, what the callback returns, and how your Callback Endpoint creates the session.
Logout: How your Logout Endpoint destroys the session, and how the SDKs revoke refresh tokens and log users out of Wristband.
Frontend Integration: How the frontend SDKs work with your backend server's auth endpoints.
Protecting Routes and APIs: How the auth middleware protects your routes and APIs.
Token Refresh: How the SDKs keep access tokens valid for the life of a session.
CSRF Protection: How the SDKs generate and validate CSRF tokens.