--- title: "Authorizestart" method: POST path: "/v1/idp/oauth/authorize/start" tags: ["Idp"] --- # Authorizestart `POST /v1/idp/oauth/authorize/start` ## Request - Base URL: `https://api.stytch.com` - URL: `https://api.stytch.com/v1/idp/oauth/authorize/start` - Auth: HTTP basic Initiates a request for authorization of a Connected App to access a User's account. Call this endpoint using the query parameters from an OAuth Authorization request. This endpoint validates various fields (`scope`, `client_id`, `redirect_uri`, `prompt`, etc...) are correct and returns relevant information for rendering an OAuth Consent Screen. This endpoint returns: - A public representation of the Connected App requesting authorization - Whether _explicit_ user consent must be granted before proceeding with the authorization - A list of scopes the user has the ability to grant the Connected App Use this response to prompt the user for consent (if necessary) before calling the [Submit OAuth Authorization](https://stytch.com/docs/api/connected-apps-oauth-authorize) endpoint. Exactly one of the following must be provided to identify the user granting authorization: - `user_id` - `session_token` - `session_jwt` If a `session_token` or `session_jwt` is passed, the OAuth Authorization will be linked to the user's session for tracking purposes. One of these fields must be used if the Connected App intends to complete the [Exchange Access Token](https://stytch.com/docs/api/connected-app-access-token-exchange) flow. ## Request body - ApiIdpV1IdpOauthAuthorizeStartRequest: Request type - `client_id` string, required: The ID of the Connected App client. - `redirect_uri` string, required: The callback URI used to redirect the user after authentication. This is the same URI provided at the start of the OAuth flow. This field is required when using the `authorization_code` grant. - `response_type` string, required: The OAuth 2.0 response type. For authorization code flows this value is `code`. - `scopes` string[], required: An array of scopes requested by the client. - `user_id` string: The unique ID of a specific User. You may use an `external_id` here if one is set for the user. - `session_token` string: The `session_token` associated with a User's existing Session. - `session_jwt` string: The `session_jwt` associated with a User's existing Session. - `prompt` string: Space separated list that specifies how the Authorization Server should prompt the user for reauthentication and consent. Only `consent` is supported today. ## Response `200` Successful response - ApiIdpV1IdpOauthAuthorizeStartResponse - `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. - `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`. - `client` ApiConnectedappsV1ConnectedAppPublic, required - `client_id` string, required - `client_name` string, required - `client_description` string, required - `client_type` string, required - `logo_url` string - `consent_required` boolean, required: Whether the user must provide explicit consent for the authorization request. - `scope_results` ApiIdpV1ScopeResult[], required: Details about each requested scope. - `scope` string, required: The name of the scope. - `description` string, required: A human-readable description of the scope, taken from the RBAC Policy. - `is_grantable` boolean, required: Indicates whether the scope can be granted. Users can only grant scopes if they have the required permissions. - `status_code` integer, required ## 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`: 2 breaking - 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-11-03** `b2acbf387799`: 1 warning - removed the request property `resources` - **2025-10-23** `4a2e3c0c0c05`: 1 breaking - added the new required request property `resources` [Operation history](https://skmtc.dev/stytch/apis/stytch-api/changes/v1/idp/oauth/authorize/start/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)