> ## Documentation Index > Fetch the complete documentation index at: https://stytch.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Start OAuth Authorization > Initiates a request for authorization of a Connected App 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](/api-reference/consumer/api/connected-apps/consent-management/submit-oauth-authorization) 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](/api-reference/consumer/api/sessions/exchange-access-token) flow. ## OpenAPI ````yaml POST /v1/idp/oauth/authorize/start openapi: 3.0.3 info: title: Stytch API description: The Stytch API provides endpoints for authentication and user management. version: 2.1.1 contact: name: Stytch Support url: https://stytch.com/docs email: support@stytch.com servers: - url: https://api.stytch.com description: Production server - url: https://test.stytch.com description: Test server security: - basicAuth: [] paths: /v1/idp/oauth/authorize/start: post: tags: - Idp summary: Authorizestart description: >- 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. operationId: api_idp_v1_idp_oauth_AuthorizeStart requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/api_idp_v1_idp_oauth_AuthorizeStartRequest' responses: '200': description: Successful response content: application/json: schema: $ref: >- #/components/schemas/api_idp_v1_idp_oauth_AuthorizeStartResponse '400': description: Bad request '401': description: Unauthorized content: application/json: example: 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 '429': description: Too Many Requests content: application/json: example: 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 '500': description: Internal server error content: application/json: example: 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 x-code-samples: - lang: csharp label: C# source: |- // POST /v1/idp/oauth/authorize/start const stytch = require('stytch'); const client = new stytch.Client({ project_id: '${projectId}', secret: '${secret}', }); const params = { client_id: "connected-app-test-d731954d-dab3-4a2b-bdee-07f3ad1be888", redirect_uri: "https://app.example/oauth/callback", response_type: "code", scopes: ["openid"], }; client.IDP.OAuth.AuthorizeStart(params) .then(resp => { console.log(resp) }) .catch(err => { console.log(err) }); - lang: go label: Go source: "// POST /v1/idp/oauth/authorize/start\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\n\t\"github.com/stytchauth/stytch-go/v18/stytch/consumer/idp/oauth\"\n\t\"github.com/stytchauth/stytch-go/v18/stytch/consumer/stytchapi\"\n)\n\nfunc main() {\n\tclient, err := stytchapi.NewClient(\n\t\t\"${projectId}\",\n\t\t\"${secret}\",\n\t)\n\tif err != nil {\n\t\tlog.Fatalf(\"error instantiating client: %v\", err)\n\t}\n\n\tparams := &oauth.AuthorizeStartParams{\n\t\tClientID: \"connected-app-test-d731954d-dab3-4a2b-bdee-07f3ad1be888\",\n\t\tRedirectURI: \"https://app.example/oauth/callback\",\n\t\tResponseType: \"code\",\n\t\tScopes: []string{\"openid\"},\n\t}\n\n\tresp, err := client.IDP.OAuth.AuthorizeStart(context.Background(), params)\n\tif err != nil {\n\t\tlog.Fatalf(\"error in method call: %v\", err)\n\t}\n\n\tlog.Println(resp)\n}\n" - lang: java label: Java source: >- // POST /v1/idp/oauth/authorize/start package com.example; import com.stytch.java.common.StytchResult; import com.stytch.java.consumer.models.idpoauth.AuthorizeStartRequest; import com.stytch.java.consumer.StytchClient; public class Main { public static void main(String[] args) { StytchClient.configure("${projectId}", "${secret}"); AuthorizeStartRequest params = new AuthorizeStartRequest(); params.setClientId("connected-app-test-d731954d-dab3-4a2b-bdee-07f3ad1be888"); params.setRedirectUri("https://app.example/oauth/callback"); params.setResponseType("code"); params.setScopes(new String("openid")); Object result = StytchClient.getIDP().getOAuth().authorizeStart(params); if (result instanceof StytchResult.Success) { System.out.println(((StytchResult.Success) result).getValue()); } else { System.out.println(((StytchResult.Error) result).getException()); } } } - lang: kotlin label: Kotlin source: > // POST /v1/idp/oauth/authorize/start package com.example import com.stytch.java.consumer.StytchClient import com.stytch.java.consumer.models.idpoauth.AuthorizeStartRequest fun main() { StytchClient.configure( projectId = "${projectId}", secret = "${secret}", ) when ( val result = StytchClient.idp.oauth.authorizeStart( AuthorizeStartRequest( clientId = "connected-app-test-d731954d-dab3-4a2b-bdee-07f3ad1be888", redirectUri = "https://app.example/oauth/callback", responseType = "code", scopes = arrayOf("openid"), ), ) ) { is StytchResult.Success -> println(result.value) is StytchResult.Error -> println(result.exception) } } - lang: javascript label: Node.js source: |- // POST /v1/idp/oauth/authorize/start const stytch = require('stytch'); const client = new stytch.Client({ project_id: '${projectId}', secret: '${secret}', }); const params = { client_id: "connected-app-test-d731954d-dab3-4a2b-bdee-07f3ad1be888", redirect_uri: "https://app.example/oauth/callback", response_type: "code", scopes: ["openid"], }; client.idp.oauth.authorizeStart(params) .then(resp => { console.log(resp) }) .catch(err => { console.log(err) }); - lang: php label: PHP source: |- $response = $client->idp->oauth->authorize_start([ 'client_id' => 'connected-app-test-d731954d-dab3-4a2b-bdee-07f3ad1be888', 'redirect_uri' => 'https://app.example/oauth/callback', 'response_type' => 'code', 'scopes' => ['openid'], ]); - lang: python label: Python source: | # POST /v1/idp/oauth/authorize/start from stytch import Client client = Client( project_id="${projectId}", secret="${secret}", ) resp = client.idp.oauth.authorize_start( client_id="connected-app-test-d731954d-dab3-4a2b-bdee-07f3ad1be888", redirect_uri="https://app.example/oauth/callback", response_type="code", scopes=["openid"], ) print(resp) - lang: ruby label: Ruby source: |- # frozen_string_literal: true # POST /v1/idp/oauth/authorize/start require 'stytch' client = Stytch::Client.new( project_id: "${projectId}", secret: "${secret}" ) resp = client.idp.oauth.authorize_start( client_id: "connected-app-test-d731954d-dab3-4a2b-bdee-07f3ad1be888", redirect_uri: "https://app.example/oauth/callback", response_type: "code", scopes: ['openid'] ) puts resp - lang: rust label: Rust source: |- // POST /v1/idp/oauth/authorize/start use stytch::consumer::client::Client; use stytch::consumer::idp_oauth::AuthorizeStartRequest; fn main() { let client = Client::new("${projectId}", "${secret}").unwrap(); let resp = client.idp.oauth.authorize_start( AuthorizeStartRequest{ client_id: "connected-app-test-d731954d-dab3-4a2b-bdee-07f3ad1be888", redirect_uri: "https://app.example/oauth/callback", response_type: "code", scopes: vec!["openid"], ..Default::default() } ).await; println!("The response is {:?}", resp); } - lang: bash label: cURL source: |- # POST /v1/idp/oauth/authorize/start curl --request POST \ --url https://test.stytch.com/v1/idp/oauth/authorize/start \ -u '${projectId}:${secret}' \ -H 'Content-Type: application/json' \ -d '{ "client_id": "connected-app-test-d731954d-dab3-4a2b-bdee-07f3ad1be888", "redirect_uri": "https://app.example/oauth/callback", "response_type": "code", "scopes": ["openid"] }' components: schemas: api_idp_v1_idp_oauth_AuthorizeStartRequest: type: object properties: client_id: type: string description: The ID of the Connected App client. redirect_uri: type: string description: >- 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: type: string description: >- The OAuth 2.0 response type. For authorization code flows this value is `code`. scopes: type: array items: type: string description: An array of scopes requested by the client. user_id: type: string description: >- The unique ID of a specific User. You may use an `external_id` here if one is set for the user. session_token: type: string description: The `session_token` associated with a User's existing Session. session_jwt: type: string description: The `session_jwt` associated with a User's existing Session. prompt: type: string description: >- Space separated list that specifies how the Authorization Server should prompt the user for reauthentication and consent. Only `consent` is supported today. description: Request type required: - client_id - redirect_uri - response_type - scopes api_idp_v1_idp_oauth_AuthorizeStartResponse: type: object properties: request_id: type: string description: >- 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: type: string description: The unique ID of the affected User. user: $ref: '#/components/schemas/api_user_v1_User' description: >- The `user` object affected by this API call. See the [Get user endpoint](https://stytch.com/docs/api/get-user) for complete response field details. client: $ref: '#/components/schemas/api_connectedapps_v1_ConnectedAppPublic' consent_required: type: boolean description: >- Whether the user must provide explicit consent for the authorization request. scope_results: type: array items: $ref: '#/components/schemas/api_idp_v1_ScopeResult' description: Details about each requested scope. status_code: type: integer format: int32 required: - request_id - user_id - user - client - consent_required - scope_results - status_code api_user_v1_User: type: object properties: user_id: type: string description: The unique ID of the affected User. emails: type: array items: $ref: '#/components/schemas/api_user_v1_Email' description: An array of email objects for the User. status: type: string description: >- The status of the User. The possible values are `pending` and `active`. phone_numbers: type: array items: $ref: '#/components/schemas/api_user_v1_PhoneNumber' description: An array of phone number objects linked to the User. webauthn_registrations: type: array items: $ref: '#/components/schemas/api_user_v1_WebAuthnRegistration' description: >- An array that contains a list of all Passkey or WebAuthn registrations for a given User in the Stytch API. providers: type: array items: $ref: '#/components/schemas/api_user_v1_OAuthProvider' description: An array of OAuth `provider` objects linked to the User. totps: type: array items: $ref: '#/components/schemas/api_user_v1_TOTP' description: >- An array containing a list of all TOTP instances for a given User in the Stytch API. crypto_wallets: type: array items: $ref: '#/components/schemas/api_user_v1_CryptoWallet' description: >- An array contains a list of all crypto wallets for a given User in the Stytch API. biometric_registrations: type: array items: $ref: '#/components/schemas/api_user_v1_BiometricRegistration' description: >- An array that contains a list of all biometric registrations for a given User in the Stytch API. is_locked: type: boolean description: >- 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: type: array items: type: string description: |- Roles assigned to this User. See the [RBAC guide](https://stytch.com/docs/guides/rbac/role-assignment) for more information about role assignment. name: $ref: '#/components/schemas/api_user_v1_Name' description: The name of the User. Each field in the `name` object is optional. created_at: type: string description: >- 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: $ref: '#/components/schemas/api_user_v1_Password' description: The password object is returned for users with a password. trusted_metadata: type: object additionalProperties: true description: >- 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: type: object additionalProperties: true description: >- 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: type: string description: >- 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: type: string description: >- 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: type: string description: >- 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`. required: - user_id - emails - status - phone_numbers - webauthn_registrations - providers - totps - crypto_wallets - biometric_registrations - is_locked - roles api_connectedapps_v1_ConnectedAppPublic: type: object properties: client_id: type: string client_name: type: string client_description: type: string client_type: type: string logo_url: type: string required: - client_id - client_name - client_description - client_type api_idp_v1_ScopeResult: type: object properties: scope: type: string description: The name of the scope. description: type: string description: >- A human-readable description of the scope, taken from the RBAC Policy. is_grantable: type: boolean description: >- Indicates whether the scope can be granted. Users can only grant scopes if they have the required permissions. required: - scope - description - is_grantable api_user_v1_Email: type: object properties: email_id: type: string description: The unique ID of a specific email address. email: type: string description: The email address. verified: type: boolean description: >- The verified boolean denotes whether or not this send method, e.g. phone number, email address, etc., has been successfully authenticated by the User. required: - email_id - email - verified api_user_v1_PhoneNumber: type: object properties: phone_id: type: string description: The unique ID for the phone number. phone_number: type: string description: The phone number. verified: type: boolean description: >- The verified boolean denotes whether or not this send method, e.g. phone number, email address, etc., has been successfully authenticated by the User. required: - phone_id - phone_number - verified api_user_v1_WebAuthnRegistration: type: object properties: webauthn_registration_id: type: string description: The unique ID for the Passkey or WebAuthn registration. domain: type: string description: >- The `domain` on which Passkey or WebAuthn registration was started. This will be the domain of your app. user_agent: type: string description: The user agent of the User. verified: type: boolean description: >- 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: type: string description: >- 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: type: string description: The `name` of the Passkey or WebAuthn registration. required: - webauthn_registration_id - domain - user_agent - verified - authenticator_type - name api_user_v1_OAuthProvider: type: object properties: provider_type: type: string description: >- Denotes the OAuth identity provider that the user has authenticated with, e.g. Google, Facebook, GitHub etc. provider_subject: type: string description: >- 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: type: string description: >- 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: type: string description: >- 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: type: string description: The unique ID for an OAuth registration. required: - provider_type - provider_subject - profile_picture_url - locale - oauth_user_registration_id api_user_v1_TOTP: type: object properties: totp_id: type: string description: The unique ID for a TOTP instance. verified: type: boolean description: >- The verified boolean denotes whether or not this send method, e.g. phone number, email address, etc., has been successfully authenticated by the User. required: - totp_id - verified api_user_v1_CryptoWallet: type: object properties: crypto_wallet_id: type: string description: The unique ID for a crypto wallet crypto_wallet_address: type: string description: The actual blockchain address of the User's crypto wallet. crypto_wallet_type: type: string description: >- The blockchain that the User's crypto wallet operates on, e.g. Ethereum, Solana, etc. verified: type: boolean description: >- The verified boolean denotes whether or not this send method, e.g. phone number, email address, etc., has been successfully authenticated by the User. required: - crypto_wallet_id - crypto_wallet_address - crypto_wallet_type - verified api_user_v1_BiometricRegistration: type: object properties: biometric_registration_id: type: string description: The unique ID for a biometric registration. verified: type: boolean description: >- The verified boolean denotes whether or not this send method, e.g. phone number, email address, etc., has been successfully authenticated by the User. required: - biometric_registration_id - verified api_user_v1_Name: type: object properties: first_name: type: string description: The first name of the user. middle_name: type: string description: The middle name(s) of the user. last_name: type: string description: The last name of the user. api_user_v1_Password: type: object properties: password_id: type: string description: The unique ID of a specific password requires_reset: type: boolean description: Indicates whether this password requires a password reset required: - password_id - requires_reset securitySchemes: basicAuth: type: http scheme: basic ````