Authenticate
Authenticate an OAuth token.
session_duration_minutes; a session with the identity provider, e.g. Google or Facebook, will always be initiated upon successful authentication.Authorizations
Body
Request type
Reuse an existing session instead of creating a new one. If you provide us with a session_token, then we'll update the session represented by this session token with this OAuth factor. If this session_token belongs to a different user than the OAuth token, the session_jwt will be ignored. This endpoint will error if both session_token and session_jwt are provided.
Set the session lifetime to be this many minutes from now. This will start a new session if one doesn't already exist,
returning both an opaque session_token and session_jwt for this session. Remember that the session_jwt will have a fixed lifetime of
five minutes regardless of the underlying session duration, and will need to be refreshed over time.
This value must be a minimum of 5 and a maximum of 527040 minutes (366 days).
If a session_token or session_jwt is provided then a successful authentication will continue to extend the session this many minutes.
If the session_duration_minutes parameter is not specified, a Stytch session will not be created.
Reuse an existing session instead of creating a new one. If you provide us with a session_jwt, then we'll update the session represented by this JWT with this OAuth factor. If this session_jwt belongs to a different user than the OAuth token, the session_jwt will be ignored. This endpoint will error if both session_token and session_jwt are provided.
Add a custom claims map to the Session being authenticated. Claims are only created if a Session is initialized by providing a value in session_duration_minutes. Claims will be included on the Session object and in the JWT. To update a key in an existing Session, supply a new value. To delete a key, supply a null value.
Custom claims made with reserved claims ("iss", "sub", "aud", "exp", "nbf", "iat", "jti") will be ignored. Total custom claims size cannot exceed four kilobytes.
If the telemetry_id is passed, as part of this request, Stytch will call the Fingerprint Lookup API and store the associated fingerprints and IPGEO information for the User. Your workspace must be enabled for Device Fingerprinting to use this feature.
Response
Successful response
The provider_values object lists relevant identifiers, values, and scopes for a given OAuth provider. For example this object will include a provider's access_token that you can use to access the provider's API for a given user.
Note that these values will vary based on the OAuth provider in question, e.g. id_token is only returned by OIDC compliant identity providers.
The user object affected by this API call. See the Get user endpoint for complete response field details.
A Session object. For backwards compatibility reasons, the session from an OAuth authenticate call is labeled as user_session, but is otherwise just a standard stytch Session object.
See Session object for complete response fields.
If a valid telemetry_id was passed in the request and the Fingerprint Lookup API returned results, the user_device response field will contain information about the user's device attributes.