curl --request POST \
--url https://api.stytch.com/v1/sessions/authenticate \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"session_token": "<string>",
"session_duration_minutes": 123,
"session_jwt": "<string>",
"session_custom_claims": {}
}
'import requests
url = "https://api.stytch.com/v1/sessions/authenticate"
payload = {
"session_token": "<string>",
"session_duration_minutes": 123,
"session_jwt": "<string>",
"session_custom_claims": {}
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
session_token: '<string>',
session_duration_minutes: 123,
session_jwt: '<string>',
session_custom_claims: {}
})
};
fetch('https://api.stytch.com/v1/sessions/authenticate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.stytch.com/v1/sessions/authenticate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'session_token' => '<string>',
'session_duration_minutes' => 123,
'session_jwt' => '<string>',
'session_custom_claims' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.stytch.com/v1/sessions/authenticate"
payload := strings.NewReader("{\n \"session_token\": \"<string>\",\n \"session_duration_minutes\": 123,\n \"session_jwt\": \"<string>\",\n \"session_custom_claims\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.stytch.com/v1/sessions/authenticate")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"session_token\": \"<string>\",\n \"session_duration_minutes\": 123,\n \"session_jwt\": \"<string>\",\n \"session_custom_claims\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.stytch.com/v1/sessions/authenticate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"session_token\": \"<string>\",\n \"session_duration_minutes\": 123,\n \"session_jwt\": \"<string>\",\n \"session_custom_claims\": {}\n}"
response = http.request(request)
puts response.read_body{
"request_id": "<string>",
"session": {
"session_id": "<string>",
"user_id": "<string>",
"authentication_factors": [
{
"type": "magic_link",
"delivery_method": "email",
"last_authenticated_at": "<string>",
"created_at": "<string>",
"updated_at": "<string>",
"email_factor": {
"email_id": "<string>",
"email_address": "<string>"
},
"phone_number_factor": {
"phone_id": "<string>",
"phone_number": "<string>"
},
"google_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"microsoft_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"apple_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"webauthn_factor": {
"webauthn_registration_id": "<string>",
"domain": "<string>",
"user_agent": "<string>"
},
"authenticator_app_factor": {
"totp_id": "<string>"
},
"github_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"recovery_code_factor": {
"totp_recovery_code_id": "<string>"
},
"facebook_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"crypto_wallet_factor": {
"crypto_wallet_id": "<string>",
"crypto_wallet_address": "<string>",
"crypto_wallet_type": "<string>"
},
"amazon_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"bitbucket_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"coinbase_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"discord_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"figma_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"git_lab_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"instagram_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"linked_in_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"shopify_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"slack_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"snapchat_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"spotify_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"steam_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"tik_tok_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"twitch_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"twitter_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"embeddable_magic_link_factor": {
"embedded_id": "<string>"
},
"biometric_factor": {
"biometric_registration_id": "<string>"
},
"saml_sso_factor": {
"id": "<string>",
"provider_id": "<string>",
"external_id": "<string>"
},
"oidc_sso_factor": {
"id": "<string>",
"provider_id": "<string>",
"external_id": "<string>"
},
"salesforce_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"yahoo_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"hubspot_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"slack_oauth_exchange_factor": {
"email_id": "<string>"
},
"hubspot_oauth_exchange_factor": {
"email_id": "<string>"
},
"github_oauth_exchange_factor": {
"email_id": "<string>"
},
"google_oauth_exchange_factor": {
"email_id": "<string>"
},
"impersonated_factor": {
"impersonator_id": "<string>",
"impersonator_email_address": "<string>"
},
"oauth_access_token_exchange_factor": {
"client_id": "<string>"
},
"trusted_auth_token_factor": {
"token_id": "<string>"
}
}
],
"roles": [
"<string>"
],
"started_at": "<string>",
"last_accessed_at": "<string>",
"expires_at": "<string>",
"attributes": {
"ip_address": "<string>",
"user_agent": "<string>"
},
"custom_claims": {}
},
"session_token": "<string>",
"session_jwt": "<string>",
"user": {
"user_id": "<string>",
"emails": [
{
"email_id": "<string>",
"email": "<string>",
"verified": true
}
],
"status": "<string>",
"phone_numbers": [
{
"phone_id": "<string>",
"phone_number": "<string>",
"verified": true
}
],
"webauthn_registrations": [
{
"webauthn_registration_id": "<string>",
"domain": "<string>",
"user_agent": "<string>",
"verified": true,
"authenticator_type": "<string>",
"name": "<string>"
}
],
"providers": [
{
"provider_type": "<string>",
"provider_subject": "<string>",
"profile_picture_url": "<string>",
"locale": "<string>",
"oauth_user_registration_id": "<string>"
}
],
"totps": [
{
"totp_id": "<string>",
"verified": true
}
],
"crypto_wallets": [
{
"crypto_wallet_id": "<string>",
"crypto_wallet_address": "<string>",
"crypto_wallet_type": "<string>",
"verified": true
}
],
"biometric_registrations": [
{
"biometric_registration_id": "<string>",
"verified": true
}
],
"is_locked": true,
"roles": [
"<string>"
],
"name": {
"first_name": "<string>",
"middle_name": "<string>",
"last_name": "<string>"
},
"created_at": "<string>",
"password": {
"password_id": "<string>",
"requires_reset": true
},
"trusted_metadata": {},
"untrusted_metadata": {},
"external_id": "<string>",
"lock_created_at": "<string>",
"lock_expires_at": "<string>"
},
"status_code": 123,
"verdict": {
"authorized": true,
"granting_roles": [
"<string>"
]
}
}{
"status_code": 401,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "unauthorized_credentials",
"error_message": "Unauthorized credentials.",
"error_url": "https://stytch.com/docs/api/errors/401"
}{
"status_code": 429,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "too_many_requests",
"error_message": "Too many requests have been made.",
"error_url": "https://stytch.com/docs/api/errors/429"
}{
"status_code": 500,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "internal_server_error",
"error_message": "Oops, something seems to have gone wrong, please reach out to support@stytch.com to let us know what went wrong.",
"error_url": "https://stytch.com/docs/api/errors/500"
}Authenticate Session
Authenticate a session token or session JWT and retrieve associated session data.
curl --request POST \
--url https://api.stytch.com/v1/sessions/authenticate \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"session_token": "<string>",
"session_duration_minutes": 123,
"session_jwt": "<string>",
"session_custom_claims": {}
}
'import requests
url = "https://api.stytch.com/v1/sessions/authenticate"
payload = {
"session_token": "<string>",
"session_duration_minutes": 123,
"session_jwt": "<string>",
"session_custom_claims": {}
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
session_token: '<string>',
session_duration_minutes: 123,
session_jwt: '<string>',
session_custom_claims: {}
})
};
fetch('https://api.stytch.com/v1/sessions/authenticate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.stytch.com/v1/sessions/authenticate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'session_token' => '<string>',
'session_duration_minutes' => 123,
'session_jwt' => '<string>',
'session_custom_claims' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.stytch.com/v1/sessions/authenticate"
payload := strings.NewReader("{\n \"session_token\": \"<string>\",\n \"session_duration_minutes\": 123,\n \"session_jwt\": \"<string>\",\n \"session_custom_claims\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.stytch.com/v1/sessions/authenticate")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"session_token\": \"<string>\",\n \"session_duration_minutes\": 123,\n \"session_jwt\": \"<string>\",\n \"session_custom_claims\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.stytch.com/v1/sessions/authenticate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"session_token\": \"<string>\",\n \"session_duration_minutes\": 123,\n \"session_jwt\": \"<string>\",\n \"session_custom_claims\": {}\n}"
response = http.request(request)
puts response.read_body{
"request_id": "<string>",
"session": {
"session_id": "<string>",
"user_id": "<string>",
"authentication_factors": [
{
"type": "magic_link",
"delivery_method": "email",
"last_authenticated_at": "<string>",
"created_at": "<string>",
"updated_at": "<string>",
"email_factor": {
"email_id": "<string>",
"email_address": "<string>"
},
"phone_number_factor": {
"phone_id": "<string>",
"phone_number": "<string>"
},
"google_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"microsoft_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"apple_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"webauthn_factor": {
"webauthn_registration_id": "<string>",
"domain": "<string>",
"user_agent": "<string>"
},
"authenticator_app_factor": {
"totp_id": "<string>"
},
"github_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"recovery_code_factor": {
"totp_recovery_code_id": "<string>"
},
"facebook_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"crypto_wallet_factor": {
"crypto_wallet_id": "<string>",
"crypto_wallet_address": "<string>",
"crypto_wallet_type": "<string>"
},
"amazon_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"bitbucket_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"coinbase_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"discord_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"figma_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"git_lab_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"instagram_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"linked_in_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"shopify_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"slack_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"snapchat_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"spotify_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"steam_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"tik_tok_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"twitch_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"twitter_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"embeddable_magic_link_factor": {
"embedded_id": "<string>"
},
"biometric_factor": {
"biometric_registration_id": "<string>"
},
"saml_sso_factor": {
"id": "<string>",
"provider_id": "<string>",
"external_id": "<string>"
},
"oidc_sso_factor": {
"id": "<string>",
"provider_id": "<string>",
"external_id": "<string>"
},
"salesforce_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"yahoo_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"hubspot_oauth_factor": {
"id": "<string>",
"provider_subject": "<string>",
"email_id": "<string>"
},
"slack_oauth_exchange_factor": {
"email_id": "<string>"
},
"hubspot_oauth_exchange_factor": {
"email_id": "<string>"
},
"github_oauth_exchange_factor": {
"email_id": "<string>"
},
"google_oauth_exchange_factor": {
"email_id": "<string>"
},
"impersonated_factor": {
"impersonator_id": "<string>",
"impersonator_email_address": "<string>"
},
"oauth_access_token_exchange_factor": {
"client_id": "<string>"
},
"trusted_auth_token_factor": {
"token_id": "<string>"
}
}
],
"roles": [
"<string>"
],
"started_at": "<string>",
"last_accessed_at": "<string>",
"expires_at": "<string>",
"attributes": {
"ip_address": "<string>",
"user_agent": "<string>"
},
"custom_claims": {}
},
"session_token": "<string>",
"session_jwt": "<string>",
"user": {
"user_id": "<string>",
"emails": [
{
"email_id": "<string>",
"email": "<string>",
"verified": true
}
],
"status": "<string>",
"phone_numbers": [
{
"phone_id": "<string>",
"phone_number": "<string>",
"verified": true
}
],
"webauthn_registrations": [
{
"webauthn_registration_id": "<string>",
"domain": "<string>",
"user_agent": "<string>",
"verified": true,
"authenticator_type": "<string>",
"name": "<string>"
}
],
"providers": [
{
"provider_type": "<string>",
"provider_subject": "<string>",
"profile_picture_url": "<string>",
"locale": "<string>",
"oauth_user_registration_id": "<string>"
}
],
"totps": [
{
"totp_id": "<string>",
"verified": true
}
],
"crypto_wallets": [
{
"crypto_wallet_id": "<string>",
"crypto_wallet_address": "<string>",
"crypto_wallet_type": "<string>",
"verified": true
}
],
"biometric_registrations": [
{
"biometric_registration_id": "<string>",
"verified": true
}
],
"is_locked": true,
"roles": [
"<string>"
],
"name": {
"first_name": "<string>",
"middle_name": "<string>",
"last_name": "<string>"
},
"created_at": "<string>",
"password": {
"password_id": "<string>",
"requires_reset": true
},
"trusted_metadata": {},
"untrusted_metadata": {},
"external_id": "<string>",
"lock_created_at": "<string>",
"lock_expires_at": "<string>"
},
"status_code": 123,
"verdict": {
"authorized": true,
"granting_roles": [
"<string>"
]
}
}{
"status_code": 401,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "unauthorized_credentials",
"error_message": "Unauthorized credentials.",
"error_url": "https://stytch.com/docs/api/errors/401"
}{
"status_code": 429,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "too_many_requests",
"error_message": "Too many requests have been made.",
"error_url": "https://stytch.com/docs/api/errors/429"
}{
"status_code": 500,
"request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
"error_type": "internal_server_error",
"error_message": "Oops, something seems to have gone wrong, please reach out to support@stytch.com to let us know what went wrong.",
"error_url": "https://stytch.com/docs/api/errors/500"
}session_duration_minutes is included, update the lifetime of the session to be that many minutes from now.
All timestamps are formatted according to the RFC 3339 standard and are expressed in UTC, e.g. 2021-12-29T12:33:09Z.
This endpoint requires exactly one session_jwt or session_token as part of the request. If both are included, you will receive a too_many_session_arguments error.
You may provide a JWT that needs to be refreshed and is expired according to its exp claim. A new JWT will be returned if both the signature and the underlying Session are still valid. See our sessions guides for more information.Authorizations
Body
Request type
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 an authorization_check object is passed in, this endpoint will also check if the User is
authorized to perform the given action on the given Resource. A User is authorized if they are assigned a Role with adequate permissions.
If the User is not authorized to perform the specified action on the specified Resource, a 403 error will be thrown. Otherwise, the response will contain a list of Roles that satisfied the authorization check.
Show child attributes
Show child attributes
Response
Successful response
If you initiate a Session, by including session_duration_minutes in your authenticate call, you'll receive a full Session object in the response.
See Session object for complete response fields.
Show child attributes
Show child attributes
The user object affected by this API call. See the Get user endpoint for complete response field details.
Show child attributes
Show child attributes