---
title: "Migrate"
method: POST
path: "/v1/sessions/migrate"
tags: ["Session"]
---

# Migrate

`POST /v1/sessions/migrate`

## Request

- Base URL: `https://api.stytch.com`
- URL: `https://api.stytch.com/v1/sessions/migrate`
- Auth: HTTP basic

Migrate a session from an external OIDC compliant endpoint. Stytch will call the external UserInfo endpoint defined in your Stytch Project settings in the [Dashboard](https://stytch.com/dashboard), and then perform a lookup using the `session_token`. If the response contains a valid email address, Stytch will attempt to match that email address with an existing User and create a Stytch Session. You will need to create the user before using this endpoint.

## Request body

- ApiSessionV1MigrateRequest: Request type
  - `session_token` string, required: The authorization token Stytch will pass in to the external userinfo endpoint.
  - `session_duration_minutes` integer: 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.
  - `session_custom_claims` object: 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.
  - `telemetry_id` string: If the `telemetry_id` is passed, as part of this request, Stytch will call the [Fingerprint Lookup API](https://stytch.com/docs/fraud/api/fingerprint-lookup) and store the associated fingerprints and IPGEO information for the User. Your workspace must be enabled for Device Fingerprinting to use this feature.

## Response `200`

Successful response

- ApiSessionV1MigrateResponse
  - `request_id` string, required: Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.
  - `user_id` string, required: The unique ID of the affected User.
  - `session_token` string, required: A secret token for a given Stytch Session.
  - `session_jwt` string, required: The JSON Web Token (JWT) for a given Stytch Session.
  - `user` ApiUserV1User, required
    - `user_id` string, required: The unique ID of the affected User.
    - `emails` ApiUserV1Email[], required: An array of email objects for the User.
      - `email_id` string, required: The unique ID of a specific email address.
      - `email` string, required: The email address.
      - `verified` boolean, required: The verified boolean denotes whether or not this send method, e.g. phone number, email address, etc., has been successfully authenticated by the User.
    - `status` string, required: The status of the User. The possible values are `pending` and `active`.
    - `phone_numbers` ApiUserV1PhoneNumber[], required: An array of phone number objects linked to the User.
      - `phone_id` string, required: The unique ID for the phone number.
      - `phone_number` string, required: The phone number.
      - `verified` boolean, required: The verified boolean denotes whether or not this send method, e.g. phone number, email address, etc., has been successfully authenticated by the User.
    - `webauthn_registrations` ApiUserV1WebAuthnRegistration[], required: An array that contains a list of all Passkey or WebAuthn registrations for a given User in the Stytch API.
      - `webauthn_registration_id` string, required: The unique ID for the Passkey or WebAuthn registration.
      - `domain` string, required: The `domain` on which Passkey or WebAuthn registration was started. This will be the domain of your app.
      - `user_agent` string, required: The user agent of the User.
      - `verified` boolean, required: The verified boolean denotes whether or not this send method, e.g. phone number, email address, etc., has been successfully authenticated by the User.
      - `authenticator_type` string, required: The `authenticator_type` string displays the requested authenticator type of the Passkey or WebAuthn device. The two valid types are "platform" and "cross-platform". If no value is present, the Passkey or WebAuthn device was created without an authenticator type preference.
      - `name` string, required: The `name` of the Passkey or WebAuthn registration.
    - `providers` ApiUserV1OAuthProvider[], required: An array of OAuth `provider` objects linked to the User.
      - `provider_type` string, required: Denotes the OAuth identity provider that the user has authenticated with, e.g. Google, Facebook, GitHub etc.
      - `provider_subject` string, required: The unique identifier for the User within a given OAuth provider. Also commonly called the "sub" or "Subject field" in OAuth protocols.
      - `profile_picture_url` string, required: If available, the `profile_picture_url` is a url of the User's profile picture set in OAuth identity the provider that the User has authenticated with, e.g. Facebook profile picture.
      - `locale` string, required: If available, the `locale` is the User's locale set in the OAuth identity provider that the user has authenticated with.
      - `oauth_user_registration_id` string, required: The unique ID for an OAuth registration.
    - `totps` ApiUserV1TOTP[], required: An array containing a list of all TOTP instances for a given User in the Stytch API.
      - `totp_id` string, required: The unique ID for a TOTP instance.
      - `verified` boolean, required: The verified boolean denotes whether or not this send method, e.g. phone number, email address, etc., has been successfully authenticated by the User.
    - `crypto_wallets` ApiUserV1CryptoWallet[], required: An array contains a list of all crypto wallets for a given User in the Stytch API.
      - `crypto_wallet_id` string, required: The unique ID for a crypto wallet
      - `crypto_wallet_address` string, required: The actual blockchain address of the User's crypto wallet.
      - `crypto_wallet_type` string, required: The blockchain that the User's crypto wallet operates on, e.g. Ethereum, Solana, etc.
      - `verified` boolean, required: The verified boolean denotes whether or not this send method, e.g. phone number, email address, etc., has been successfully authenticated by the User.
    - `biometric_registrations` ApiUserV1BiometricRegistration[], required: An array that contains a list of all biometric registrations for a given User in the Stytch API.
      - `biometric_registration_id` string, required: The unique ID for a biometric registration.
      - `verified` boolean, required: The verified boolean denotes whether or not this send method, e.g. phone number, email address, etc., has been successfully authenticated by the User.
    - `is_locked` boolean, required: Whether the User is temporarily locked due to too many failed authentication attempts. See the [User Locking Guide](https://stytch.com/docs/resources/platform/user-locks) for more information.
    - `roles` string[], required: Roles assigned to this User. See the [RBAC guide](https://stytch.com/docs/guides/rbac/role-assignment) for more information about role assignment.
    - `name` ApiUserV1Name
      - `first_name` string: The first name of the user.
      - `middle_name` string: The middle name(s) of the user.
      - `last_name` string: The last name of the user.
    - `created_at` string: The timestamp of the User's creation. Values conform to the RFC 3339 standard and are expressed in UTC, e.g. `2021-12-29T12:33:09Z`.
    - `password` ApiUserV1Password
      - `password_id` string, required: The unique ID of a specific password
      - `requires_reset` boolean, required: Indicates whether this password requires a password reset
    - `trusted_metadata` object: The `trusted_metadata` field contains an arbitrary JSON object of application-specific data. See the [Metadata](https://stytch.com/docs/api/metadata) reference for complete field behavior details.
    - `untrusted_metadata` object: The `untrusted_metadata` field contains an arbitrary JSON object of application-specific data. Untrusted metadata can be edited by end users directly via the SDK, and **cannot be used to store critical information.** See the [Metadata](https://stytch.com/docs/api/metadata) reference for complete field behavior details.
    - `external_id` string: An identifier that can be used in most API calls where a `member_id` is expected. This is a string consisting of alphanumeric, `.`, `_`, `-`, or `|` characters with a maximum length of 128 characters. External IDs must be unique within the project.
    - `lock_created_at` string: When the user lock was created, if there is one. Values conform to the RFC 3339 standard and are expressed in UTC, e.g. `2021-12-29T12:33:09Z`.
    - `lock_expires_at` string: When the user lock expires, if there is one. Values conform to the RFC 3339 standard and are expressed in UTC, e.g. `2021-12-29T12:33:09Z`.
  - `status_code` integer, required
  - `session` ApiSessionV1Session
    - `session_id` string, required: A unique identifier for a specific Session.
    - `user_id` string, required: The unique ID of the affected User.
    - `authentication_factors` ApiSessionV1AuthenticationFactor[], required: An array of different authentication factors that comprise a Session.
      - `type` 'magic_link' | 'otp' | 'oauth' | 'webauthn' | 'totp' | 'crypto' | 'password' | 'signature_challenge' | 'sso' | 'imported' | 'recovery_codes' | 'email_otp' | 'impersonated' | 'trusted_auth_token', required
      - `delivery_method` 'email' | 'sms' | 'whatsapp' | 'embedded' | 'oauth_google' | 'oauth_microsoft' | 'oauth_apple' | 'webauthn_registration' | 'authenticator_app' | 'oauth_github' | 'recovery_code' | 'oauth_facebook' | 'crypto_wallet' | 'oauth_amazon' | 'oauth_bitbucket' | 'oauth_coinbase' | 'oauth_discord' | 'oauth_figma' | 'oauth_gitlab' | 'oauth_instagram' | 'oauth_linkedin' | 'oauth_shopify' | 'oauth_slack' | 'oauth_snapchat' | 'oauth_spotify' | 'oauth_steam' | 'oauth_tiktok' | 'oauth_twitch' | 'oauth_twitter' | 'knowledge' | 'biometric' | 'sso_saml' | 'sso_oidc' | 'oauth_salesforce' | 'oauth_yahoo' | 'oauth_hubspot' | 'imported_auth0' | 'oauth_exchange_slack' | 'oauth_exchange_hubspot' | 'oauth_exchange_github' | 'oauth_exchange_google' | 'impersonation' | 'oauth_access_token_exchange' | 'trusted_token_exchange', required
      - `last_authenticated_at` string: The timestamp when the factor was last authenticated.
      - `created_at` string: The timestamp when the factor was initially authenticated.
      - `updated_at` string: The timestamp when the factor was last updated.
      - `email_factor` ApiSessionV1EmailFactor
        - `email_id` string, required: The globally unique UUID of the Member's email.
        - `email_address` string, required: The email address of the Member.
      - `phone_number_factor` ApiSessionV1PhoneNumberFactor
        - `phone_id` string, required: The globally unique UUID of the Member's phone number.
        - `phone_number` string, required: The phone number of the Member.
      - `google_oauth_factor` ApiSessionV1GoogleOAuthFactor
        - `id` string, required: The unique ID of an OAuth registration.
        - `provider_subject` string, required: The unique identifier for the User within a given OAuth provider. Also commonly called the `sub` or "Subject field" in OAuth protocols.
        - `email_id` string: The globally unique UUID of the Member's email.
      - `microsoft_oauth_factor` ApiSessionV1MicrosoftOAuthFactor
        - `id` string, required: The unique ID of an OAuth registration.
        - `provider_subject` string, required: The unique identifier for the User within a given OAuth provider. Also commonly called the `sub` or "Subject field" in OAuth protocols.
        - `email_id` string: The globally unique UUID of the Member's email.
      - `apple_oauth_factor` ApiSessionV1AppleOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `webauthn_factor` ApiSessionV1WebAuthnFactor
        - `webauthn_registration_id` string, required
        - `domain` string, required
        - `user_agent` string
      - `authenticator_app_factor` ApiSessionV1AuthenticatorAppFactor
        - `totp_id` string, required: Globally unique UUID that identifies a TOTP instance.
      - `github_oauth_factor` ApiSessionV1GithubOAuthFactor
        - `id` string, required: The unique ID of an OAuth registration.
        - `provider_subject` string, required: The unique identifier for the User within a given OAuth provider. Also commonly called the `sub` or "Subject field" in OAuth protocols.
        - `email_id` string: The globally unique UUID of the Member's email.
      - `recovery_code_factor` ApiSessionV1RecoveryCodeFactor
        - `totp_recovery_code_id` string, required
      - `facebook_oauth_factor` ApiSessionV1FacebookOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `crypto_wallet_factor` ApiSessionV1CryptoWalletFactor
        - `crypto_wallet_id` string, required
        - `crypto_wallet_address` string, required
        - `crypto_wallet_type` string, required
      - `amazon_oauth_factor` ApiSessionV1AmazonOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `bitbucket_oauth_factor` ApiSessionV1BitbucketOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `coinbase_oauth_factor` ApiSessionV1CoinbaseOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `discord_oauth_factor` ApiSessionV1DiscordOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `figma_oauth_factor` ApiSessionV1FigmaOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `git_lab_oauth_factor` ApiSessionV1GitLabOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `instagram_oauth_factor` ApiSessionV1InstagramOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `linked_in_oauth_factor` ApiSessionV1LinkedInOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `shopify_oauth_factor` ApiSessionV1ShopifyOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `slack_oauth_factor` ApiSessionV1SlackOAuthFactor
        - `id` string, required: The unique ID of an OAuth registration.
        - `provider_subject` string, required: The unique identifier for the User within a given OAuth provider. Also commonly called the `sub` or "Subject field" in OAuth protocols.
        - `email_id` string: The globally unique UUID of the Member's email.
      - `snapchat_oauth_factor` ApiSessionV1SnapchatOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `spotify_oauth_factor` ApiSessionV1SpotifyOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `steam_oauth_factor` ApiSessionV1SteamOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `tik_tok_oauth_factor` ApiSessionV1TikTokOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `twitch_oauth_factor` ApiSessionV1TwitchOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `twitter_oauth_factor` ApiSessionV1TwitterOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `embeddable_magic_link_factor` ApiSessionV1EmbeddableMagicLinkFactor
        - `embedded_id` string, required
      - `biometric_factor` ApiSessionV1BiometricFactor
        - `biometric_registration_id` string, required
      - `saml_sso_factor` ApiSessionV1SAMLSSOFactor
        - `id` string, required: The unique ID of an SSO Registration.
        - `provider_id` string, required: Globally unique UUID that identifies a specific SAML Connection.
        - `external_id` string, required: The ID of the member given by the identity provider.
      - `oidc_sso_factor` ApiSessionV1OIDCSSOFactor
        - `id` string, required: The unique ID of an SSO Registration.
        - `provider_id` string, required: Globally unique UUID that identifies a specific OIDC Connection.
        - `external_id` string, required: The ID of the member given by the identity provider.
      - `salesforce_oauth_factor` ApiSessionV1SalesforceOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `yahoo_oauth_factor` ApiSessionV1YahooOAuthFactor
        - `id` string, required
        - `provider_subject` string, required
        - `email_id` string
      - `hubspot_oauth_factor` ApiSessionV1HubspotOAuthFactor
        - `id` string, required: The unique ID of an OAuth registration.
        - `provider_subject` string, required: The unique identifier for the User within a given OAuth provider. Also commonly called the `sub` or "Subject field" in OAuth protocols.
        - `email_id` string: The globally unique UUID of the Member's email.
      - `slack_oauth_exchange_factor` ApiSessionV1SlackOAuthExchangeFactor
        - `email_id` string, required: The globally unique UUID of the Member's email.
      - `hubspot_oauth_exchange_factor` ApiSessionV1HubspotOAuthExchangeFactor
        - `email_id` string, required: The globally unique UUID of the Member's email.
      - `github_oauth_exchange_factor` ApiSessionV1GithubOAuthExchangeFactor
        - `email_id` string, required: The globally unique UUID of the Member's email.
      - `google_oauth_exchange_factor` ApiSessionV1GoogleOAuthExchangeFactor
        - `email_id` string, required: The globally unique UUID of the Member's email.
      - `impersonated_factor` ApiSessionV1ImpersonatedFactor
        - `impersonator_id` string, required: For impersonated sessions initiated via the Stytch Dashboard, the `impersonator_id` will be the impersonator's Stytch Dashboard `member_id`.
        - `impersonator_email_address` string, required: The email address of the impersonator.
      - `oauth_access_token_exchange_factor` ApiSessionV1OAuthAccessTokenExchangeFactor
        - `client_id` string, required: The ID of the Connected App client.
      - `trusted_auth_token_factor` ApiSessionV1TrustedAuthTokenFactor
        - `token_id` string, required: The ID of the trusted auth token.
    - `roles` string[], required
    - `started_at` string: The timestamp when the Session was created. Values conform to the RFC 3339 standard and are expressed in UTC, e.g. `2021-12-29T12:33:09Z`.
    - `last_accessed_at` string: The timestamp when the Session was last accessed. Values conform to the RFC 3339 standard and are expressed in UTC, e.g. `2021-12-29T12:33:09Z`.
    - `expires_at` string: The timestamp when the Session expires. Values conform to the RFC 3339 standard and are expressed in UTC, e.g. `2021-12-29T12:33:09Z`.
    - `attributes` ApiAttributeV1Attributes
      - `ip_address` string: The IP address of the user.
      - `user_agent` string: The user agent of the User.
    - `custom_claims` object: The custom claims map for a Session. Claims can be added to a session during a Sessions authenticate call.
  - `user_device` ApiDeviceHistoryV1DeviceInfo
    - `visitor_id` string, required: The `visitor_id` (a unique identifier) of the user's device. See the [Device Fingerprinting documentation](https://stytch.com/docs/fraud/guides/device-fingerprinting/fingerprints) for more details on the `visitor_id`.
    - `visitor_id_details` ApiDeviceHistoryV1DeviceAttributeDetails
      - `is_new` boolean, required: Whether this `ip_geo_country` has been seen before for this user.
      - `first_seen_at` string: When this `ip_geo_country` was first seen for this user. Values conform to the RFC 3339 standard and are expressed in UTC, e.g. `2021-12-29T12:33:09Z`.
      - `last_seen_at` string: When this `ip_geo_country` was last seen for this user. Values conform to the RFC 3339 standard and are expressed in UTC, e.g. `2021-12-29T12:33:09Z`.
    - `ip_address` string: The IP address of the user's device.
    - `ip_address_details` ApiDeviceHistoryV1DeviceAttributeDetails
      - `is_new` boolean, required: Whether this `ip_geo_country` has been seen before for this user.
      - `first_seen_at` string: When this `ip_geo_country` was first seen for this user. Values conform to the RFC 3339 standard and are expressed in UTC, e.g. `2021-12-29T12:33:09Z`.
      - `last_seen_at` string: When this `ip_geo_country` was last seen for this user. Values conform to the RFC 3339 standard and are expressed in UTC, e.g. `2021-12-29T12:33:09Z`.
    - `ip_geo_city` string: The city where the IP address is located.
    - `ip_geo_region` string: The region where the IP address is located.
    - `ip_geo_country` string: The country code where the IP address is located.
    - `ip_geo_country_details` ApiDeviceHistoryV1DeviceAttributeDetails
      - `is_new` boolean, required: Whether this `ip_geo_country` has been seen before for this user.
      - `first_seen_at` string: When this `ip_geo_country` was first seen for this user. Values conform to the RFC 3339 standard and are expressed in UTC, e.g. `2021-12-29T12:33:09Z`.
      - `last_seen_at` string: When this `ip_geo_country` was last seen for this user. Values conform to the RFC 3339 standard and are expressed in UTC, e.g. `2021-12-29T12:33:09Z`.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `429`: Too Many Requests
- `500`: Internal server error

## Changes

- **2026-03-07** `110f26a94e5b`: 1 info
  - endpoint added
- **2026-03-06** `9cab20b8eca7`: 1 breaking
  - api path removed without deprecation
- **2026-01-09** `7dfcc14e566c`: 4 breaking
  - the `session_custom_claims` request property type changed from `string` to `object`
  - the `session/custom_claims` response's property type changed from `string` to `object` for status `200`
  - the `user/trusted_metadata` response's property type changed from `string` to `object` for status `200`
  - the `user/untrusted_metadata` response's property type changed from `string` to `object` for status `200`
- **2025-10-07** `86607f94fcf8`: 1 info
  - added the required property `session/roles` to the response with the `200` status
- **2025-09-24** `d1a2040cf009`: 1 info
  - added the required property `user/roles` to the response with the `200` status

[Operation history](https://skmtc.dev/stytch/apis/stytch-api/changes/v1/sessions/migrate/post.md)

---

[API](https://skmtc.dev/stytch/apis/stytch-api.md) - [All operations](https://skmtc.dev/stytch/apis/stytch-api/llms.txt) - [OpenAPI document](https://skmtc.dev/stytch/apis/stytch-api/revisions/6d1ff7474803?raw)