openapi: 3.0.3 info: title: Stytch B2B Authentication Application OTP API version: 2.0.0 description: Stytch's B2B API for multi-tenant authentication. Supports Organizations, Members, SSO (SAML/OIDC), Magic Links, OTP, OAuth, Discovery, Sessions, B2B RBAC, SCIM, TOTP, Recovery Codes, Passwords, Impersonation, and the B2B IDP. contact: name: Stytch url: https://stytch.com/docs license: name: Proprietary servers: - url: https://api.stytch.com description: Production - url: https://test.stytch.com description: Test tags: - name: OTP paths: /v1/otps/authenticate: post: summary: Authenticate operationId: api_otp_v1_Authenticate tags: - OTP description: Authenticate a User given a `method_id` (the associated `email_id` or `phone_id`) and a `code`. This endpoint verifies that the code is valid, hasn't expired or been previously used, and any optional security settings such as IP match or user agent match are satisfied. A given `method_id` may only have a single active OTP code at any given time, if a User requests another OTP code before the first one has expired, the first one will be invalidated. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/api_otp_v1_AuthenticateRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/api_otp_v1_AuthenticateResponse' '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/otps/authenticate\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n project_id: '${projectId}',\n secret: '${secret}',\n});\n\nconst params = {\n method_id: \"${phoneId}\",\n code: \"${exampleCode}\",\n session_duration_minutes: 60,\n};\n\nclient.OTPs.Authenticate(params)\n .then(resp => { console.log(resp) })\n .catch(err => { console.log(err) });" - lang: go label: Go source: "// POST /v1/otps/authenticate\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\n\t\"github.com/stytchauth/stytch-go/v17/stytch/consumer/otp\"\n\t\"github.com/stytchauth/stytch-go/v17/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 := &otp.AuthenticateParams{\n\t\tMethodID: \"${phoneId}\",\n\t\tCode: \"${exampleCode}\",\n\t\tSessionDurationMinutes: 60,\n\t}\n\n\tresp, err := client.OTPs.Authenticate(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/otps/authenticate\npackage com.example;\n\nimport com.stytch.java.common.StytchResult;\nimport com.stytch.java.consumer.models.otp.AuthenticateRequest;\nimport com.stytch.java.consumer.StytchClient;\n\npublic class Main {\n public static void main(String[] args) {\n StytchClient.configure(\"${projectId}\", \"${secret}\");\n\n AuthenticateRequest params = new AuthenticateRequest();\n params.setMethodId(\"${phoneId}\");\n params.setCode(\"${exampleCode}\");\n params.setSessionDurationMinutes(60);\n\n Object result = StytchClient.getOTPs().authenticate(params);\n if (result instanceof StytchResult.Success) {\n System.out.println(((StytchResult.Success) result).getValue());\n } else {\n System.out.println(((StytchResult.Error) result).getException());\n }\n }\n}" - lang: kotlin label: Kotlin source: "// POST /v1/otps/authenticate\npackage com.example\n\nimport com.stytch.java.consumer.StytchClient\nimport com.stytch.java.consumer.models.otp.AuthenticateRequest\n\nfun main() {\n StytchClient.configure(\n projectId = \"${projectId}\",\n secret = \"${secret}\",\n )\n\n when (\n val result =\n StytchClient.otps.authenticate(\n AuthenticateRequest(\n methodId = \"${phoneId}\",\n code = \"${exampleCode}\",\n sessionDurationMinutes = 60,\n ),\n )\n ) {\n is StytchResult.Success -> println(result.value)\n is StytchResult.Error -> println(result.exception)\n }\n}\n" - lang: javascript label: Node.js source: "// POST /v1/otps/authenticate\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n project_id: '${projectId}',\n secret: '${secret}',\n});\n\nconst params = {\n method_id: \"${phoneId}\",\n code: \"${exampleCode}\",\n session_duration_minutes: 60,\n};\n\nclient.otps.authenticate(params)\n .then(resp => { console.log(resp) })\n .catch(err => { console.log(err) });" - lang: php label: PHP source: "$response = $client->otps->authenticate([\n 'method_id' => '${phoneId}',\n 'code' => '${exampleCode}',\n 'session_duration_minutes' => 60,\n]);" - lang: python label: Python source: "# POST /v1/otps/authenticate\nfrom stytch import Client\n\nclient = Client(\n project_id=\"${projectId}\",\n secret=\"${secret}\",\n)\n\nresp = client.otps.authenticate(\n method_id=\"${phoneId}\",\n code=\"${exampleCode}\",\n session_duration_minutes=60,\n)\n\nprint(resp)\n" - lang: ruby label: Ruby source: "# POST /v1/otps/authenticate\nrequire 'stytch'\n\nclient = Stytch::Client.new(\n project_id: \"${projectId}\",\n secret: \"${secret}\"\n)\n\nresp = client.otps.authenticate(\n method_id: \"${phoneId}\",\n code: \"${exampleCode}\",\n session_duration_minutes: 60\n \n)\n\nputs resp" - lang: rust label: Rust source: "// POST /v1/otps/authenticate\nuse stytch::consumer::client::Client;\nuse stytch::consumer::otp::AuthenticateRequest;\n\nfn main() {\n let client = Client::new(\"${projectId}\", \"${secret}\").unwrap();\n let resp = client.otps.authenticate(\n AuthenticateRequest{\n method_id: \"${phoneId}\",\n code: \"${exampleCode}\",\n session_duration_minutes: 60,\n ..Default::default()\n }\n ).await;\n println!(\"The response is {:?}\", resp);\n}" - lang: bash label: cURL source: "# POST /v1/otps/authenticate\ncurl --request POST \\\n --url https://test.stytch.com/v1/otps/authenticate \\\n -u '${projectId}:${secret}' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"method_id\": \"${phoneId}\",\n \"code\": \"${exampleCode}\",\n \"session_duration_minutes\": 60\n }'" /v1/otps/sms/send: post: summary: Send operationId: api_otp_v1_otp_sms_Send tags: - OTP description: 'Send a one-time passcode (OTP) to a user''s phone number. If you''d like to create a user and send them a passcode with one request, use our [log in or create](https://stytch.com/docs/api/log-in-or-create-user-by-sms) endpoint. Note that sending another OTP code before the first has expired will invalidate the first code. ### Cost to send SMS OTP Before configuring SMS or WhatsApp OTPs, please review how Stytch [bills the costs of international OTPs](https://stytch.com/pricing) and understand how to protect your app against [toll fraud](https://stytch.com/docs/guides/passcodes/toll-fraud/overview). __Note:__ SMS to phone numbers outside of the US and Canada is disabled by default for customers who did not use SMS prior to October 2023. If you''re interested in sending international SMS, please add those countries to your Project''s allowlist via the [Dashboard](https://stytch.com/dashboard/country-code-allowlists) or [Programmatic Workspace Actions](https://stytch.com/docs/workspace-management/pwa/set-allowed-country-codes), and [add credit card details](https://stytch.com/dashboard/settings/billing) to your account. Even when international SMS is enabled, we do not support sending SMS to countries on our [Unsupported countries list](https://stytch.com/docs/guides/passcodes/unsupported-countries). ### Add a phone number to an existing user This endpoint also allows you to add a new phone number to an existing Stytch User. Including a `user_id`, `session_token`, or `session_jwt` in your Send one-time passcode by SMS request will add the new, unverified phone number to the existing Stytch User. If the user successfully authenticates within 5 minutes, the new phone number will be marked as verified and remain permanently on the existing Stytch User. Otherwise, it will be removed from the User object, and any subsequent login requests using that phone number will create a new User. ### Next steps Collect the OTP which was delivered to the user. Call [Authenticate OTP](https://stytch.com/docs/api/authenticate-otp) using the OTP `code` along with the `phone_id` found in the response as the `method_id`.' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/api_otp_v1_otp_sms_SendRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/api_otp_v1_otp_sms_SendResponse' '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/otps/sms/send\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n project_id: '${projectId}',\n secret: '${secret}',\n});\n\nconst params = {\n phone_number: \"${examplePhoneNumber}\",\n};\n\nclient.OTPs.Sms.Send(params)\n .then(resp => { console.log(resp) })\n .catch(err => { console.log(err) });" - lang: go label: Go source: "// POST /v1/otps/sms/send\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\n\t\"github.com/stytchauth/stytch-go/v17/stytch/consumer/otp/sms\"\n\t\"github.com/stytchauth/stytch-go/v17/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 := &sms.SendParams{\n\t\tPhoneNumber: \"${examplePhoneNumber}\",\n\t}\n\n\tresp, err := client.OTPs.Sms.Send(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/otps/sms/send\npackage com.example;\n\nimport com.stytch.java.common.StytchResult;\nimport com.stytch.java.consumer.models.otpsms.SendRequest;\nimport com.stytch.java.consumer.StytchClient;\n\npublic class Main {\n public static void main(String[] args) {\n StytchClient.configure(\"${projectId}\", \"${secret}\");\n\n SendRequest params = new SendRequest();\n params.setPhoneNumber(\"${examplePhoneNumber}\");\n\n Object result = StytchClient.getOTPs().getSms().send(params);\n if (result instanceof StytchResult.Success) {\n System.out.println(((StytchResult.Success) result).getValue());\n } else {\n System.out.println(((StytchResult.Error) result).getException());\n }\n }\n}" - lang: kotlin label: Kotlin source: "// POST /v1/otps/sms/send\npackage com.example\n\nimport com.stytch.java.consumer.StytchClient\nimport com.stytch.java.consumer.models.otpsms.SendRequest\n\nfun main() {\n StytchClient.configure(\n projectId = \"${projectId}\",\n secret = \"${secret}\",\n )\n\n when (\n val result =\n StytchClient.otps.sms.send(\n SendRequest(\n phoneNumber = \"${examplePhoneNumber}\",\n ),\n )\n ) {\n is StytchResult.Success -> println(result.value)\n is StytchResult.Error -> println(result.exception)\n }\n}\n" - lang: javascript label: Node.js source: "// POST /v1/otps/sms/send\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n project_id: '${projectId}',\n secret: '${secret}',\n});\n\nconst params = {\n phone_number: \"${examplePhoneNumber}\",\n};\n\nclient.otps.sms.send(params)\n .then(resp => { console.log(resp) })\n .catch(err => { console.log(err) });" - lang: php label: PHP source: "$response = $client->otps->sms->send([\n 'phone_number' => '${examplePhoneNumber}',\n]);" - lang: python label: Python source: "# POST /v1/otps/sms/send\nfrom stytch import Client\n\nclient = Client(\n project_id=\"${projectId}\",\n secret=\"${secret}\",\n)\n\nresp = client.otps.sms.send(\n phone_number=\"${examplePhoneNumber}\",\n)\n\nprint(resp)\n" - lang: ruby label: Ruby source: "# POST /v1/otps/sms/send\nrequire 'stytch'\n\nclient = Stytch::Client.new(\n project_id: \"${projectId}\",\n secret: \"${secret}\"\n)\n\nresp = client.otps.sms.send(\n phone_number: \"${examplePhoneNumber}\"\n \n)\n\nputs resp" - lang: rust label: Rust source: "// POST /v1/otps/sms/send\nuse stytch::consumer::client::Client;\nuse stytch::consumer::otp_sms::SendRequest;\n\nfn main() {\n let client = Client::new(\"${projectId}\", \"${secret}\").unwrap();\n let resp = client.otps.sms.send(\n SendRequest{\n phone_number: \"${examplePhoneNumber}\",\n ..Default::default()\n }\n ).await;\n println!(\"The response is {:?}\", resp);\n}" - lang: bash label: cURL source: "# POST /v1/otps/sms/send\ncurl --request POST \\\n --url https://test.stytch.com/v1/otps/sms/send \\\n -u '${projectId}:${secret}' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"phone_number\": \"${examplePhoneNumber}\"\n }'" /v1/otps/sms/login_or_create: post: summary: Loginorcreate operationId: api_otp_v1_otp_sms_LoginOrCreate tags: - OTP description: 'Send a One-Time Passcode (OTP) to a User using their phone number. If the phone number is not associated with a user already, a user will be created. ### Cost to send SMS OTP Before configuring SMS or WhatsApp OTPs, please review how Stytch [bills the costs of international OTPs](https://stytch.com/pricing) and understand how to protect your app against [toll fraud](https://stytch.com/docs/guides/passcodes/toll-fraud/overview). __Note:__ SMS to phone numbers outside of the US and Canada is disabled by default for customers who did not use SMS prior to October 2023. If you''re interested in sending international SMS, please add those countries to your Project''s allowlist via the [Dashboard](https://stytch.com/dashboard/country-code-allowlists) or [Programmatic Workspace Actions](https://stytch.com/docs/workspace-management/pwa/set-allowed-country-codes), and [add credit card details](https://stytch.com/dashboard/settings/billing) to your account. Even when international SMS is enabled, we do not support sending SMS to countries on our [Unsupported countries list](https://stytch.com/docs/guides/passcodes/unsupported-countries). ### Next steps Collect the OTP which was delivered to the User. Call [Authenticate OTP](https://stytch.com/docs/api/authenticate-otp) using the OTP `code` along with the `phone_id` found in the response as the `method_id`.' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/api_otp_v1_otp_sms_LoginOrCreateRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/api_otp_v1_otp_sms_LoginOrCreateResponse' '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/otps/sms/login_or_create\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n project_id: '${projectId}',\n secret: '${secret}',\n});\n\nconst params = {\n phone_number: \"${examplePhoneNumber}\",\n};\n\nclient.OTPs.Sms.LoginOrCreate(params)\n .then(resp => { console.log(resp) })\n .catch(err => { console.log(err) });" - lang: go label: Go source: "// POST /v1/otps/sms/login_or_create\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\n\t\"github.com/stytchauth/stytch-go/v17/stytch/consumer/otp/sms\"\n\t\"github.com/stytchauth/stytch-go/v17/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 := &sms.LoginOrCreateParams{\n\t\tPhoneNumber: \"${examplePhoneNumber}\",\n\t}\n\n\tresp, err := client.OTPs.Sms.LoginOrCreate(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/otps/sms/login_or_create\npackage com.example;\n\nimport com.stytch.java.common.StytchResult;\nimport com.stytch.java.consumer.models.otpsms.LoginOrCreateRequest;\nimport com.stytch.java.consumer.StytchClient;\n\npublic class Main {\n public static void main(String[] args) {\n StytchClient.configure(\"${projectId}\", \"${secret}\");\n\n LoginOrCreateRequest params = new LoginOrCreateRequest();\n params.setPhoneNumber(\"${examplePhoneNumber}\");\n\n Object result = StytchClient.getOTPs().getSms().loginOrCreate(params);\n if (result instanceof StytchResult.Success) {\n System.out.println(((StytchResult.Success) result).getValue());\n } else {\n System.out.println(((StytchResult.Error) result).getException());\n }\n }\n}" - lang: kotlin label: Kotlin source: "// POST /v1/otps/sms/login_or_create\npackage com.example\n\nimport com.stytch.java.consumer.StytchClient\nimport com.stytch.java.consumer.models.otpsms.LoginOrCreateRequest\n\nfun main() {\n StytchClient.configure(\n projectId = \"${projectId}\",\n secret = \"${secret}\",\n )\n\n when (\n val result =\n StytchClient.otps.sms.loginOrCreate(\n LoginOrCreateRequest(\n phoneNumber = \"${examplePhoneNumber}\",\n ),\n )\n ) {\n is StytchResult.Success -> println(result.value)\n is StytchResult.Error -> println(result.exception)\n }\n}\n" - lang: javascript label: Node.js source: "// POST /v1/otps/sms/login_or_create\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n project_id: '${projectId}',\n secret: '${secret}',\n});\n\nconst params = {\n phone_number: \"${examplePhoneNumber}\",\n};\n\nclient.otps.sms.loginOrCreate(params)\n .then(resp => { console.log(resp) })\n .catch(err => { console.log(err) });" - lang: php label: PHP source: "$response = $client->otps->sms->login_or_create([\n 'phone_number' => '${examplePhoneNumber}',\n]);" - lang: python label: Python source: "# POST /v1/otps/sms/login_or_create\nfrom stytch import Client\n\nclient = Client(\n project_id=\"${projectId}\",\n secret=\"${secret}\",\n)\n\nresp = client.otps.sms.login_or_create(\n phone_number=\"${examplePhoneNumber}\",\n)\n\nprint(resp)\n" - lang: ruby label: Ruby source: "# POST /v1/otps/sms/login_or_create\nrequire 'stytch'\n\nclient = Stytch::Client.new(\n project_id: \"${projectId}\",\n secret: \"${secret}\"\n)\n\nresp = client.otps.sms.login_or_create(\n phone_number: \"${examplePhoneNumber}\"\n \n)\n\nputs resp" - lang: rust label: Rust source: "// POST /v1/otps/sms/login_or_create\nuse stytch::consumer::client::Client;\nuse stytch::consumer::otp_sms::LoginOrCreateRequest;\n\nfn main() {\n let client = Client::new(\"${projectId}\", \"${secret}\").unwrap();\n let resp = client.otps.sms.login_or_create(\n LoginOrCreateRequest{\n phone_number: \"${examplePhoneNumber}\",\n ..Default::default()\n }\n ).await;\n println!(\"The response is {:?}\", resp);\n}" - lang: bash label: cURL source: "# POST /v1/otps/sms/login_or_create\ncurl --request POST \\\n --url https://test.stytch.com/v1/otps/sms/login_or_create \\\n -u '${projectId}:${secret}' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"phone_number\": \"${examplePhoneNumber}\"\n }'" /v1/otps/whatsapp/send: post: summary: Send operationId: api_otp_v1_otp_whatsapp_Send tags: - OTP description: 'Send a One-Time Passcode (OTP) to a User''s WhatsApp. If you''d like to create a user and send them a passcode with one request, use our [log in or create](https://stytch.com/docs/api/whatsapp-login-or-create) endpoint. Note that sending another OTP code before the first has expired will invalidate the first code. ### Cost to send SMS OTP Before configuring SMS or WhatsApp OTPs, please review how Stytch [bills the costs of international OTPs](https://stytch.com/pricing) and understand how to protect your app against [toll fraud](https://stytch.com/docs/guides/passcodes/toll-fraud/overview). ### Add a phone number to an existing user This endpoint also allows you to add a new phone number to an existing Stytch User. Including a `user_id`, `session_token`, or `session_jwt` in your Send one-time passcode by WhatsApp request will add the new, unverified phone number to the existing Stytch User. If the user successfully authenticates within 5 minutes, the new phone number will be marked as verified and remain permanently on the existing Stytch User. Otherwise, it will be removed from the User object, and any subsequent login requests using that phone number will create a new User. ### Next steps Collect the OTP which was delivered to the user. Call [Authenticate OTP](https://stytch.com/docs/api/authenticate-otp) using the OTP `code` along with the `phone_id` found in the response as the `method_id`.' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/api_otp_v1_otp_whatsapp_SendRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/api_otp_v1_otp_whatsapp_SendResponse' '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/otps/whatsapp/send\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n project_id: '${projectId}',\n secret: '${secret}',\n});\n\nconst params = {\n phone_number: \"${examplePhoneNumber}\",\n};\n\nclient.OTPs.WhatsApp.Send(params)\n .then(resp => { console.log(resp) })\n .catch(err => { console.log(err) });" - lang: go label: Go source: "// POST /v1/otps/whatsapp/send\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\n\t\"github.com/stytchauth/stytch-go/v17/stytch/consumer/otp/whatsapp\"\n\t\"github.com/stytchauth/stytch-go/v17/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 := &whatsapp.SendParams{\n\t\tPhoneNumber: \"${examplePhoneNumber}\",\n\t}\n\n\tresp, err := client.OTPs.WhatsApp.Send(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/otps/whatsapp/send\npackage com.example;\n\nimport com.stytch.java.common.StytchResult;\nimport com.stytch.java.consumer.models.otpwhatsapp.SendRequest;\nimport com.stytch.java.consumer.StytchClient;\n\npublic class Main {\n public static void main(String[] args) {\n StytchClient.configure(\"${projectId}\", \"${secret}\");\n\n SendRequest params = new SendRequest();\n params.setPhoneNumber(\"${examplePhoneNumber}\");\n\n Object result = StytchClient.getOTPs().getWhatsApp().send(params);\n if (result instanceof StytchResult.Success) {\n System.out.println(((StytchResult.Success) result).getValue());\n } else {\n System.out.println(((StytchResult.Error) result).getException());\n }\n }\n}" - lang: kotlin label: Kotlin source: "// POST /v1/otps/whatsapp/send\npackage com.example\n\nimport com.stytch.java.consumer.StytchClient\nimport com.stytch.java.consumer.models.otpwhatsapp.SendRequest\n\nfun main() {\n StytchClient.configure(\n projectId = \"${projectId}\",\n secret = \"${secret}\",\n )\n\n when (\n val result =\n StytchClient.otps.whatsapp.send(\n SendRequest(\n phoneNumber = \"${examplePhoneNumber}\",\n ),\n )\n ) {\n is StytchResult.Success -> println(result.value)\n is StytchResult.Error -> println(result.exception)\n }\n}\n" - lang: javascript label: Node.js source: "// POST /v1/otps/whatsapp/send\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n project_id: '${projectId}',\n secret: '${secret}',\n});\n\nconst params = {\n phone_number: \"${examplePhoneNumber}\",\n};\n\nclient.otps.whatsapp.send(params)\n .then(resp => { console.log(resp) })\n .catch(err => { console.log(err) });" - lang: php label: PHP source: "$response = $client->otps->whatsapp->send([\n 'phone_number' => '${examplePhoneNumber}',\n]);" - lang: python label: Python source: "# POST /v1/otps/whatsapp/send\nfrom stytch import Client\n\nclient = Client(\n project_id=\"${projectId}\",\n secret=\"${secret}\",\n)\n\nresp = client.otps.whatsapp.send(\n phone_number=\"${examplePhoneNumber}\",\n)\n\nprint(resp)\n" - lang: ruby label: Ruby source: "# POST /v1/otps/whatsapp/send\nrequire 'stytch'\n\nclient = Stytch::Client.new(\n project_id: \"${projectId}\",\n secret: \"${secret}\"\n)\n\nresp = client.otps.whatsapp.send(\n phone_number: \"${examplePhoneNumber}\"\n \n)\n\nputs resp" - lang: rust label: Rust source: "// POST /v1/otps/whatsapp/send\nuse stytch::consumer::client::Client;\nuse stytch::consumer::otp_whatsapp::SendRequest;\n\nfn main() {\n let client = Client::new(\"${projectId}\", \"${secret}\").unwrap();\n let resp = client.otps.whatsapp.send(\n SendRequest{\n phone_number: \"${examplePhoneNumber}\",\n ..Default::default()\n }\n ).await;\n println!(\"The response is {:?}\", resp);\n}" - lang: bash label: cURL source: "# POST /v1/otps/whatsapp/send\ncurl --request POST \\\n --url https://test.stytch.com/v1/otps/whatsapp/send \\\n -u '${projectId}:${secret}' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"phone_number\": \"${examplePhoneNumber}\"\n }'" /v1/otps/whatsapp/login_or_create: post: summary: Loginorcreate operationId: api_otp_v1_otp_whatsapp_LoginOrCreate tags: - OTP description: 'Send a one-time passcode (OTP) to a User''s WhatsApp using their phone number. If the phone number is not associated with a User already, a User will be created. ### Cost to send SMS OTP Before configuring SMS or WhatsApp OTPs, please review how Stytch [bills the costs of international OTPs](https://stytch.com/pricing) and understand how to protect your app against [toll fraud](https://stytch.com/docs/guides/passcodes/toll-fraud/overview). ### Next steps Collect the OTP which was delivered to the User. Call [Authenticate OTP](https://stytch.com/docs/api/authenticate-otp) using the OTP `code` along with the `phone_id` found in the response as the `method_id`.' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/api_otp_v1_otp_whatsapp_LoginOrCreateRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/api_otp_v1_otp_whatsapp_LoginOrCreateResponse' '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/otps/whatsapp/login_or_create\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n project_id: '${projectId}',\n secret: '${secret}',\n});\n\nconst params = {\n phone_number: \"${examplePhoneNumber}\",\n};\n\nclient.OTPs.WhatsApp.LoginOrCreate(params)\n .then(resp => { console.log(resp) })\n .catch(err => { console.log(err) });" - lang: go label: Go source: "// POST /v1/otps/whatsapp/login_or_create\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\n\t\"github.com/stytchauth/stytch-go/v17/stytch/consumer/otp/whatsapp\"\n\t\"github.com/stytchauth/stytch-go/v17/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 := &whatsapp.LoginOrCreateParams{\n\t\tPhoneNumber: \"${examplePhoneNumber}\",\n\t}\n\n\tresp, err := client.OTPs.WhatsApp.LoginOrCreate(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/otps/whatsapp/login_or_create\npackage com.example;\n\nimport com.stytch.java.common.StytchResult;\nimport com.stytch.java.consumer.models.otpwhatsapp.LoginOrCreateRequest;\nimport com.stytch.java.consumer.StytchClient;\n\npublic class Main {\n public static void main(String[] args) {\n StytchClient.configure(\"${projectId}\", \"${secret}\");\n\n LoginOrCreateRequest params = new LoginOrCreateRequest();\n params.setPhoneNumber(\"${examplePhoneNumber}\");\n\n Object result = StytchClient.getOTPs().getWhatsApp().loginOrCreate(params);\n if (result instanceof StytchResult.Success) {\n System.out.println(((StytchResult.Success) result).getValue());\n } else {\n System.out.println(((StytchResult.Error) result).getException());\n }\n }\n}" - lang: kotlin label: Kotlin source: "// POST /v1/otps/whatsapp/login_or_create\npackage com.example\n\nimport com.stytch.java.consumer.StytchClient\nimport com.stytch.java.consumer.models.otpwhatsapp.LoginOrCreateRequest\n\nfun main() {\n StytchClient.configure(\n projectId = \"${projectId}\",\n secret = \"${secret}\",\n )\n\n when (\n val result =\n StytchClient.otps.whatsapp.loginOrCreate(\n LoginOrCreateRequest(\n phoneNumber = \"${examplePhoneNumber}\",\n ),\n )\n ) {\n is StytchResult.Success -> println(result.value)\n is StytchResult.Error -> println(result.exception)\n }\n}\n" - lang: javascript label: Node.js source: "// POST /v1/otps/whatsapp/login_or_create\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n project_id: '${projectId}',\n secret: '${secret}',\n});\n\nconst params = {\n phone_number: \"${examplePhoneNumber}\",\n};\n\nclient.otps.whatsapp.loginOrCreate(params)\n .then(resp => { console.log(resp) })\n .catch(err => { console.log(err) });" - lang: php label: PHP source: "$response = $client->otps->whatsapp->login_or_create([\n 'phone_number' => '${examplePhoneNumber}',\n]);" - lang: python label: Python source: "# POST /v1/otps/whatsapp/login_or_create\nfrom stytch import Client\n\nclient = Client(\n project_id=\"${projectId}\",\n secret=\"${secret}\",\n)\n\nresp = client.otps.whatsapp.login_or_create(\n phone_number=\"${examplePhoneNumber}\",\n)\n\nprint(resp)\n" - lang: ruby label: Ruby source: "# POST /v1/otps/whatsapp/login_or_create\nrequire 'stytch'\n\nclient = Stytch::Client.new(\n project_id: \"${projectId}\",\n secret: \"${secret}\"\n)\n\nresp = client.otps.whatsapp.login_or_create(\n phone_number: \"${examplePhoneNumber}\"\n \n)\n\nputs resp" - lang: rust label: Rust source: "// POST /v1/otps/whatsapp/login_or_create\nuse stytch::consumer::client::Client;\nuse stytch::consumer::otp_whatsapp::LoginOrCreateRequest;\n\nfn main() {\n let client = Client::new(\"${projectId}\", \"${secret}\").unwrap();\n let resp = client.otps.whatsapp.login_or_create(\n LoginOrCreateRequest{\n phone_number: \"${examplePhoneNumber}\",\n ..Default::default()\n }\n ).await;\n println!(\"The response is {:?}\", resp);\n}" - lang: bash label: cURL source: "# POST /v1/otps/whatsapp/login_or_create\ncurl --request POST \\\n --url https://test.stytch.com/v1/otps/whatsapp/login_or_create \\\n -u '${projectId}:${secret}' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"phone_number\": \"${examplePhoneNumber}\"\n }'" /v1/otps/email/send: post: summary: Send operationId: api_otp_v1_otp_email_Send tags: - OTP description: 'Send a One-Time Passcode (OTP) to a User using their email. If you''d like to create a user and send them a passcode with one request, use our [log in or create endpoint](https://stytch.com/docs/api/log-in-or-create-user-by-email-otp). ### Add an email to an existing user This endpoint also allows you to add a new email address to an existing Stytch User. Including a `user_id`, `session_token`, or `session_jwt` in your Send one-time passcode by email request will add the new, unverified email address to the existing Stytch User. If the user successfully authenticates within 5 minutes, the new email address will be marked as verified and remain permanently on the existing Stytch User. Otherwise, it will be removed from the User object, and any subsequent login requests using that email address will create a new User. ### Next steps Collect the OTP which was delivered to the user. Call [Authenticate OTP](https://stytch.com/docs/api/authenticate-otp) using the OTP `code` along with the `email_id` found in the response as the `method_id`.' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/api_otp_v1_otp_email_SendRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/api_otp_v1_otp_email_SendResponse' '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/otps/email/send\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n project_id: '${projectId}',\n secret: '${secret}',\n});\n\nconst params = {\n email: \"${email}\",\n};\n\nclient.OTPs.Email.Send(params)\n .then(resp => { console.log(resp) })\n .catch(err => { console.log(err) });" - lang: go label: Go source: "// POST /v1/otps/email/send\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\n\t\"github.com/stytchauth/stytch-go/v17/stytch/consumer/otp/email\"\n\t\"github.com/stytchauth/stytch-go/v17/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 := &email.SendParams{\n\t\tEmail: \"${email}\",\n\t}\n\n\tresp, err := client.OTPs.Email.Send(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/otps/email/send\npackage com.example;\n\nimport com.stytch.java.common.StytchResult;\nimport com.stytch.java.consumer.models.otpemail.SendRequest;\nimport com.stytch.java.consumer.StytchClient;\n\npublic class Main {\n public static void main(String[] args) {\n StytchClient.configure(\"${projectId}\", \"${secret}\");\n\n SendRequest params = new SendRequest();\n params.setEmail(\"${email}\");\n\n Object result = StytchClient.getOTPs().getEmail().send(params);\n if (result instanceof StytchResult.Success) {\n System.out.println(((StytchResult.Success) result).getValue());\n } else {\n System.out.println(((StytchResult.Error) result).getException());\n }\n }\n}" - lang: kotlin label: Kotlin source: "// POST /v1/otps/email/send\npackage com.example\n\nimport com.stytch.java.consumer.StytchClient\nimport com.stytch.java.consumer.models.otpemail.SendRequest\n\nfun main() {\n StytchClient.configure(\n projectId = \"${projectId}\",\n secret = \"${secret}\",\n )\n\n when (\n val result =\n StytchClient.otps.email.send(\n SendRequest(\n email = \"${email}\",\n ),\n )\n ) {\n is StytchResult.Success -> println(result.value)\n is StytchResult.Error -> println(result.exception)\n }\n}\n" - lang: javascript label: Node.js source: "// POST /v1/otps/email/send\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n project_id: '${projectId}',\n secret: '${secret}',\n});\n\nconst params = {\n email: \"${email}\",\n};\n\nclient.otps.email.send(params)\n .then(resp => { console.log(resp) })\n .catch(err => { console.log(err) });" - lang: php label: PHP source: "$response = $client->otps->email->send([\n 'email' => '${email}',\n]);" - lang: python label: Python source: "# POST /v1/otps/email/send\nfrom stytch import Client\n\nclient = Client(\n project_id=\"${projectId}\",\n secret=\"${secret}\",\n)\n\nresp = client.otps.email.send(\n email=\"${email}\",\n)\n\nprint(resp)\n" - lang: ruby label: Ruby source: "# POST /v1/otps/email/send\nrequire 'stytch'\n\nclient = Stytch::Client.new(\n project_id: \"${projectId}\",\n secret: \"${secret}\"\n)\n\nresp = client.otps.email.send(\n email: \"${email}\"\n \n)\n\nputs resp" - lang: rust label: Rust source: "// POST /v1/otps/email/send\nuse stytch::consumer::client::Client;\nuse stytch::consumer::otp_email::SendRequest;\n\nfn main() {\n let client = Client::new(\"${projectId}\", \"${secret}\").unwrap();\n let resp = client.otps.email.send(\n SendRequest{\n email: \"${email}\",\n ..Default::default()\n }\n ).await;\n println!(\"The response is {:?}\", resp);\n}" - lang: bash label: cURL source: "# POST /v1/otps/email/send\ncurl --request POST \\\n --url https://test.stytch.com/v1/otps/email/send \\\n -u '${projectId}:${secret}' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"email\": \"${email}\"\n }'" /v1/otps/email/login_or_create: post: summary: Loginorcreate operationId: api_otp_v1_otp_email_LoginOrCreate tags: - OTP description: 'Send a one-time passcode (OTP) to a User using their email. If the email is not associated with a User already, a User will be created. ### Next steps Collect the OTP which was delivered to the User. Call [Authenticate OTP](https://stytch.com/docs/api/authenticate-otp) using the OTP `code` along with the `phone_id` found in the response as the `method_id`.' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/api_otp_v1_otp_email_LoginOrCreateRequest' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/api_otp_v1_otp_email_LoginOrCreateResponse' '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/otps/email/login_or_create\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n project_id: '${projectId}',\n secret: '${secret}',\n});\n\nconst params = {\n email: \"${email}\",\n};\n\nclient.OTPs.Email.LoginOrCreate(params)\n .then(resp => { console.log(resp) })\n .catch(err => { console.log(err) });" - lang: go label: Go source: "// POST /v1/otps/email/login_or_create\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\n\t\"github.com/stytchauth/stytch-go/v17/stytch/consumer/otp/email\"\n\t\"github.com/stytchauth/stytch-go/v17/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 := &email.LoginOrCreateParams{\n\t\tEmail: \"${email}\",\n\t}\n\n\tresp, err := client.OTPs.Email.LoginOrCreate(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/otps/email/login_or_create\npackage com.example;\n\nimport com.stytch.java.common.StytchResult;\nimport com.stytch.java.consumer.models.otpemail.LoginOrCreateRequest;\nimport com.stytch.java.consumer.StytchClient;\n\npublic class Main {\n public static void main(String[] args) {\n StytchClient.configure(\"${projectId}\", \"${secret}\");\n\n LoginOrCreateRequest params = new LoginOrCreateRequest();\n params.setEmail(\"${email}\");\n\n Object result = StytchClient.getOTPs().getEmail().loginOrCreate(params);\n if (result instanceof StytchResult.Success) {\n System.out.println(((StytchResult.Success) result).getValue());\n } else {\n System.out.println(((StytchResult.Error) result).getException());\n }\n }\n}" - lang: kotlin label: Kotlin source: "// POST /v1/otps/email/login_or_create\npackage com.example\n\nimport com.stytch.java.consumer.StytchClient\nimport com.stytch.java.consumer.models.otpemail.LoginOrCreateRequest\n\nfun main() {\n StytchClient.configure(\n projectId = \"${projectId}\",\n secret = \"${secret}\",\n )\n\n when (\n val result =\n StytchClient.otps.email.loginOrCreate(\n LoginOrCreateRequest(\n email = \"${email}\",\n ),\n )\n ) {\n is StytchResult.Success -> println(result.value)\n is StytchResult.Error -> println(result.exception)\n }\n}\n" - lang: javascript label: Node.js source: "// POST /v1/otps/email/login_or_create\nconst stytch = require('stytch');\n\nconst client = new stytch.Client({\n project_id: '${projectId}',\n secret: '${secret}',\n});\n\nconst params = {\n email: \"${email}\",\n};\n\nclient.otps.email.loginOrCreate(params)\n .then(resp => { console.log(resp) })\n .catch(err => { console.log(err) });" - lang: php label: PHP source: "$response = $client->otps->email->login_or_create([\n 'email' => '${email}',\n]);" - lang: python label: Python source: "# POST /v1/otps/email/login_or_create\nfrom stytch import Client\n\nclient = Client(\n project_id=\"${projectId}\",\n secret=\"${secret}\",\n)\n\nresp = client.otps.email.login_or_create(\n email=\"${email}\",\n)\n\nprint(resp)\n" - lang: ruby label: Ruby source: "# POST /v1/otps/email/login_or_create\nrequire 'stytch'\n\nclient = Stytch::Client.new(\n project_id: \"${projectId}\",\n secret: \"${secret}\"\n)\n\nresp = client.otps.email.login_or_create(\n email: \"${email}\"\n \n)\n\nputs resp" - lang: rust label: Rust source: "// POST /v1/otps/email/login_or_create\nuse stytch::consumer::client::Client;\nuse stytch::consumer::otp_email::LoginOrCreateRequest;\n\nfn main() {\n let client = Client::new(\"${projectId}\", \"${secret}\").unwrap();\n let resp = client.otps.email.login_or_create(\n LoginOrCreateRequest{\n email: \"${email}\",\n ..Default::default()\n }\n ).await;\n println!(\"The response is {:?}\", resp);\n}" - lang: bash label: cURL source: "# POST /v1/otps/email/login_or_create\ncurl --request POST \\\n --url https://test.stytch.com/v1/otps/email/login_or_create \\\n -u '${projectId}:${secret}' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"email\": \"${email}\"\n }'" components: schemas: api_session_v1_SlackOAuthFactor: type: object properties: id: type: string description: The unique ID of an OAuth registration. 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. email_id: type: string description: The globally unique UUID of the Member's email. required: - id - provider_subject api_magic_v1_Options: type: object properties: ip_match_required: type: boolean description: Require that the IP address the Magic Link was requested from matches the IP address it's clicked from. user_agent_match_required: type: boolean description: Require that the user agent the Magic Link was requested from matches the user agent it's clicked from. required: - ip_match_required - user_agent_match_required api_session_v1_HubspotOAuthFactor: type: object properties: id: type: string description: The unique ID of an OAuth registration. 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. email_id: type: string description: The globally unique UUID of the Member's email. required: - id - provider_subject api_session_v1_TwitchOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject api_session_v1_EmbeddableMagicLinkFactor: type: object properties: embedded_id: type: string required: - embedded_id api_otp_v1_AuthenticateRequest: type: object properties: method_id: type: string description: The `email_id` or `phone_id` involved in the given authentication. code: type: string description: The code to authenticate. attributes: $ref: '#/components/schemas/api_attribute_v1_Attributes' description: Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application. options: $ref: '#/components/schemas/api_magic_v1_Options' description: Specify optional security settings. session_token: type: string description: The `session_token` associated with a User's existing Session. session_duration_minutes: type: integer format: int32 description: "Set the session lifetime to be this many minutes from now. This will start a new session if one doesn't already exist,\n returning both an opaque `session_token` and `session_jwt` for this session. Remember that the `session_jwt` will have a fixed lifetime of\n five minutes regardless of the underlying session duration, and will need to be refreshed over time.\n\n This value must be a minimum of 5 and a maximum of 527040 minutes (366 days).\n\n If a `session_token` or `session_jwt` is provided then a successful authentication will continue to extend the session this many minutes.\n\n If the `session_duration_minutes` parameter is not specified, a Stytch session will not be created." session_jwt: type: string description: The `session_jwt` associated with a User's existing Session. session_custom_claims: type: object additionalProperties: true description: "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.\n\n 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: type: string description: 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. description: Request type required: - method_id - code api_otp_v1_otp_sms_LoginOrCreateRequest: type: object properties: phone_number: type: string description: The phone number to use for one-time passcodes. The phone number should be in E.164 format (i.e. +1XXXXXXXXXX). You may use +10000000000 to test this endpoint, see [Testing](https://stytch.com/docs/home#resources_testing) for more detail. expiration_minutes: type: integer format: int32 description: Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes. attributes: $ref: '#/components/schemas/api_attribute_v1_Attributes' description: Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application. create_user_as_pending: type: boolean description: "Flag for whether or not to save a user as pending vs active in Stytch. Defaults to false.\n If true, users will be saved with status pending in Stytch's backend until authenticated.\n If false, users will be created as active. An example usage of\n a true flag would be to require users to verify their phone by entering the OTP code before creating\n an account for them." locale: $ref: '#/components/schemas/api_otp_v1_LoginOrCreateRequestLocale' description: 'Used to determine which language to use when sending the user this delivery method. Parameter is an [IETF BCP 47 language tag](https://www.w3.org/International/articles/language-tags/), e.g. `"en"`. Currently supported languages are English (`"en"`), Spanish (`"es"`), French (`"fr"`) and Brazilian Portuguese (`"pt-br"`); if no value is provided, the copy defaults to English. Request support for additional languages [here](https://docs.google.com/forms/d/e/1FAIpQLScZSpAu_m2AmLXRT3F3kap-s_mcV6UTBitYn6CdyWP0-o7YjQ/viewform?usp=sf_link")! ' description: Request type required: - phone_number api_otp_v1_otp_sms_LoginOrCreateResponse: 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. phone_id: type: string description: The unique ID for the phone number. user_created: type: boolean description: In `login_or_create` endpoints, this field indicates whether or not a User was just created. status_code: type: integer format: int32 description: The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors. required: - request_id - user_id - phone_id - user_created - status_code api_session_v1_EmailFactor: type: object properties: email_id: type: string description: The globally unique UUID of the Member's email. email_address: type: string description: The email address of the Member. required: - email_id - email_address api_device_history_v1_DeviceInfo: type: object properties: visitor_id: type: string description: 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: $ref: '#/components/schemas/api_device_history_v1_DeviceAttributeDetails' description: Information about the `visitor_id`. ip_address: type: string description: The IP address of the user's device. ip_address_details: $ref: '#/components/schemas/api_device_history_v1_DeviceAttributeDetails' description: Information about the `ip_address`. ip_geo_city: type: string description: The city where the IP address is located. ip_geo_region: type: string description: The region where the IP address is located. ip_geo_country: type: string description: The country code where the IP address is located. ip_geo_country_details: $ref: '#/components/schemas/api_device_history_v1_DeviceAttributeDetails' description: Information about the `ip_geo_country`. required: - visitor_id api_session_v1_SteamOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject 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_session_v1_BitbucketOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject api_session_v1_OAuthAccessTokenExchangeFactor: type: object properties: client_id: type: string description: The ID of the Connected App client. required: - client_id api_session_v1_DiscordOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject api_session_v1_TrustedAuthTokenFactor: type: object properties: token_id: type: string description: The ID of the trusted auth token. required: - token_id api_session_v1_AppleOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject api_session_v1_ShopifyOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject api_session_v1_SalesforceOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject api_session_v1_AmazonOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject api_attribute_v1_Attributes: type: object properties: ip_address: type: string description: The IP address of the user. user_agent: type: string description: The user agent of the User. api_otp_v1_otp_sms_SendResponse: 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. phone_id: type: string description: The unique ID for the phone number. status_code: type: integer format: int32 description: The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors. required: - request_id - user_id - phone_id - status_code api_otp_v1_otp_whatsapp_SendResponse: 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. phone_id: type: string description: The unique ID for the phone number. status_code: type: integer format: int32 description: The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors. required: - request_id - user_id - phone_id - status_code api_session_v1_YahooOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject api_session_v1_TwitterOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject api_session_v1_AuthenticationFactorDeliveryMethod: type: string enum: - 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 api_otp_v1_AuthenticateResponse: 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. method_id: type: string description: The `email_id` or `phone_id` involved in the given authentication. session_token: type: string description: A secret token for a given Stytch Session. session_jwt: type: string description: The JSON Web Token (JWT) for a given Stytch Session. 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. reset_sessions: type: boolean description: Indicates if all other of the User's Sessions need to be reset. You should check this field if you aren't using Stytch's Session product. If you are using Stytch's Session product, we revoke the User's other sessions for you. status_code: type: integer format: int32 description: The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors. session: $ref: '#/components/schemas/api_session_v1_Session' description: "If you initiate a Session, by including `session_duration_minutes` in your authenticate call, you'll receive a full Session object in the response.\n\n See [Session object](https://stytch.com/docs/api/session-object) for complete response fields.\n " user_device: $ref: '#/components/schemas/api_device_history_v1_DeviceInfo' description: If a valid `telemetry_id` was passed in the request and the [Fingerprint Lookup API](https://stytch.com/docs/fraud/api/fingerprint-lookup) returned results, the `user_device` response field will contain information about the user's device attributes. required: - request_id - user_id - method_id - session_token - session_jwt - user - reset_sessions - status_code api_session_v1_AuthenticationFactorType: type: string enum: - magic_link - otp - oauth - webauthn - totp - crypto - password - signature_challenge - sso - imported - recovery_codes - email_otp - impersonated - trusted_auth_token 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_otp_v1_otp_email_LoginOrCreateRequest: type: object properties: email: type: string description: The email address of the user to send the one-time passcode to. You may use sandbox@stytch.com to test this endpoint, see [Testing](https://stytch.com/docs/home#resources_testing) for more detail. expiration_minutes: type: integer format: int32 description: Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes. attributes: $ref: '#/components/schemas/api_attribute_v1_Attributes' description: Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application. create_user_as_pending: type: boolean description: "Flag for whether or not to save a user as pending vs active in Stytch. Defaults to false.\n If true, users will be saved with status pending in Stytch's backend until authenticated.\n If false, users will be created as active. An example usage of\n a true flag would be to require users to verify their phone by entering the OTP code before creating\n an account for them." locale: $ref: '#/components/schemas/api_otp_v1_LoginOrCreateRequestLocale' description: 'Used to determine which language to use when sending the user this delivery method. Parameter is an [IETF BCP 47 language tag](https://www.w3.org/International/articles/language-tags/), e.g. `"en"`. Currently supported languages are English (`"en"`), Spanish (`"es"`), French (`"fr"`) and Brazilian Portuguese (`"pt-br"`); if no value is provided, the copy defaults to English. Request support for additional languages [here](https://docs.google.com/forms/d/e/1FAIpQLScZSpAu_m2AmLXRT3F3kap-s_mcV6UTBitYn6CdyWP0-o7YjQ/viewform?usp=sf_link")! ' login_template_id: type: string description: Use a custom template for login emails. By default, it will use your default email template. Templates can be added in the [Stytch dashboard](https://stytch.com/dashboard/templates) using our built-in customization options or custom HTML templates with type “Magic links - Login”. signup_template_id: type: string description: Use a custom template for sign-up emails. By default, it will use your default email template. Templates can be added in the [Stytch dashboard](https://stytch.com/dashboard/templates) using our built-in customization options or custom HTML templates with type “Magic links - Sign-up”. description: Request type required: - email api_session_v1_GoogleOAuthFactor: type: object properties: id: type: string description: The unique ID of an OAuth registration. 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. email_id: type: string description: The globally unique UUID of the Member's email. required: - id - provider_subject 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_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_session_v1_SpotifyOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject 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_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.\n 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_otp_v1_otp_email_SendRequest: type: object properties: email: type: string description: The email address of the user to send the one-time passcode to. You may use sandbox@stytch.com to test this endpoint, see [Testing](https://stytch.com/docs/home#resources_testing) for more detail. expiration_minutes: type: integer format: int32 description: Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes. attributes: $ref: '#/components/schemas/api_attribute_v1_Attributes' description: Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application. locale: $ref: '#/components/schemas/api_otp_v1_SendRequestLocale' description: 'Used to determine which language to use when sending the user this delivery method. Parameter is an [IETF BCP 47 language tag](https://www.w3.org/International/articles/language-tags/), e.g. `"en"`. Currently supported languages are English (`"en"`), Spanish (`"es"`), French (`"fr"`) and Brazilian Portuguese (`"pt-br"`); if no value is provided, the copy defaults to English. Request support for additional languages [here](https://docs.google.com/forms/d/e/1FAIpQLScZSpAu_m2AmLXRT3F3kap-s_mcV6UTBitYn6CdyWP0-o7YjQ/viewform?usp=sf_link")! ' 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. login_template_id: type: string description: Use a custom template for login emails. By default, it will use your default email template. Templates can be added in the [Stytch dashboard](https://stytch.com/dashboard/templates) using our built-in customization options or custom HTML templates with type “OTP - Login”. signup_template_id: type: string description: Use a custom template for sign-up emails. By default, it will use your default email template. Templates can be added in the [Stytch dashboard](https://stytch.com/dashboard/templates) using our built-in customization options or custom HTML templates with type “OTP - Sign-up”. description: Request type required: - email api_session_v1_GitLabOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject api_session_v1_SAMLSSOFactor: type: object properties: id: type: string description: The unique ID of an SSO Registration. provider_id: type: string description: Globally unique UUID that identifies a specific SAML Connection. external_id: type: string description: The ID of the member given by the identity provider. required: - id - provider_id - external_id api_otp_v1_otp_email_SendResponse: 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. email_id: type: string description: The unique ID of a specific email address. status_code: type: integer format: int32 description: The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors. required: - request_id - user_id - email_id - status_code 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 api_session_v1_CryptoWalletFactor: type: object properties: crypto_wallet_id: type: string crypto_wallet_address: type: string crypto_wallet_type: type: string required: - crypto_wallet_id - crypto_wallet_address - crypto_wallet_type api_session_v1_Session: type: object properties: session_id: type: string description: A unique identifier for a specific Session. user_id: type: string description: The unique ID of the affected User. authentication_factors: type: array items: $ref: '#/components/schemas/api_session_v1_AuthenticationFactor' description: An array of different authentication factors that comprise a Session. roles: type: array items: type: string started_at: type: string description: 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: type: string description: 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: type: string description: 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: $ref: '#/components/schemas/api_attribute_v1_Attributes' description: Provided attributes help with fraud detection. custom_claims: type: object additionalProperties: true description: The custom claims map for a Session. Claims can be added to a session during a Sessions authenticate call. required: - session_id - user_id - authentication_factors - roles api_session_v1_AuthenticationFactor: type: object properties: type: $ref: '#/components/schemas/api_session_v1_AuthenticationFactorType' description: "The type of authentication factor. The possible values are: `email_otp`, `impersonated`, `imported`,\n `magic_link`, `oauth`, `otp`, `password`, `recovery_codes`, `sso`, `trusted_auth_token`, or `totp`." delivery_method: $ref: '#/components/schemas/api_session_v1_AuthenticationFactorDeliveryMethod' description: "The method that was used to deliver the authentication factor. The possible values depend on the `type`:\n \n `email_otp` – Only `email`.\n \n `impersonated` – Only `impersonation`.\n \n `imported` – Only `imported_auth0`.\n \n `magic_link` – Only `email`.\n \n `oauth` – The delivery method is determined by the specific OAuth provider used. The possible values are `oauth_google`, `oauth_microsoft`, `oauth_hubspot`, `oauth_slack`, or `oauth_github`.\n \n In addition, you may see an 'exchange' delivery method when a non-email-verifying OAuth factor originally authenticated in one organization is exchanged for a factor in another organization.\n This can happen during authentication flows such as [session exchange](https://stytch.com/docs/b2b/api/exchange-session).\n The non-email-verifying OAuth providers are Hubspot, Slack, and Github.\n Google is also considered non-email-verifying when the HD claim is empty.\n The possible exchange values are `oauth_exchange_google`, `oauth_exchange_hubspot`, `oauth_exchange_slack`, or `oauth_exchange_github`.\n \n The final possible value is `oauth_access_token_exchange`, if this factor came from an [access token exchange flow](https://stytch.com/docs/b2b/api/connected-app-access-token-exchange).\n \n `otp` – Only `sms`.\n \n `password` – Only `knowledge`.\n \n `recovery_codes` – Only `recovery_code`.\n \n `sso` – Either `sso_saml` or `sso_oidc`.\n \n `trusted_auth_token` – Only `trusted_token_exchange`.\n \n `totp` – Only `authenticator_app`.\n " last_authenticated_at: type: string description: The timestamp when the factor was last authenticated. created_at: type: string description: The timestamp when the factor was initially authenticated. updated_at: type: string description: The timestamp when the factor was last updated. email_factor: $ref: '#/components/schemas/api_session_v1_EmailFactor' description: Information about the email factor, if one is present. phone_number_factor: $ref: '#/components/schemas/api_session_v1_PhoneNumberFactor' description: Information about the phone number factor, if one is present. google_oauth_factor: $ref: '#/components/schemas/api_session_v1_GoogleOAuthFactor' description: Information about the Google OAuth factor, if one is present. microsoft_oauth_factor: $ref: '#/components/schemas/api_session_v1_MicrosoftOAuthFactor' description: Information about the Microsoft OAuth factor, if one is present. apple_oauth_factor: $ref: '#/components/schemas/api_session_v1_AppleOAuthFactor' webauthn_factor: $ref: '#/components/schemas/api_session_v1_WebAuthnFactor' authenticator_app_factor: $ref: '#/components/schemas/api_session_v1_AuthenticatorAppFactor' description: Information about the TOTP-backed Authenticator App factor, if one is present. github_oauth_factor: $ref: '#/components/schemas/api_session_v1_GithubOAuthFactor' description: Information about the Github OAuth factor, if one is present. recovery_code_factor: $ref: '#/components/schemas/api_session_v1_RecoveryCodeFactor' facebook_oauth_factor: $ref: '#/components/schemas/api_session_v1_FacebookOAuthFactor' crypto_wallet_factor: $ref: '#/components/schemas/api_session_v1_CryptoWalletFactor' amazon_oauth_factor: $ref: '#/components/schemas/api_session_v1_AmazonOAuthFactor' bitbucket_oauth_factor: $ref: '#/components/schemas/api_session_v1_BitbucketOAuthFactor' coinbase_oauth_factor: $ref: '#/components/schemas/api_session_v1_CoinbaseOAuthFactor' discord_oauth_factor: $ref: '#/components/schemas/api_session_v1_DiscordOAuthFactor' figma_oauth_factor: $ref: '#/components/schemas/api_session_v1_FigmaOAuthFactor' git_lab_oauth_factor: $ref: '#/components/schemas/api_session_v1_GitLabOAuthFactor' instagram_oauth_factor: $ref: '#/components/schemas/api_session_v1_InstagramOAuthFactor' linked_in_oauth_factor: $ref: '#/components/schemas/api_session_v1_LinkedInOAuthFactor' shopify_oauth_factor: $ref: '#/components/schemas/api_session_v1_ShopifyOAuthFactor' slack_oauth_factor: $ref: '#/components/schemas/api_session_v1_SlackOAuthFactor' description: Information about the Slack OAuth factor, if one is present. snapchat_oauth_factor: $ref: '#/components/schemas/api_session_v1_SnapchatOAuthFactor' spotify_oauth_factor: $ref: '#/components/schemas/api_session_v1_SpotifyOAuthFactor' steam_oauth_factor: $ref: '#/components/schemas/api_session_v1_SteamOAuthFactor' tik_tok_oauth_factor: $ref: '#/components/schemas/api_session_v1_TikTokOAuthFactor' twitch_oauth_factor: $ref: '#/components/schemas/api_session_v1_TwitchOAuthFactor' twitter_oauth_factor: $ref: '#/components/schemas/api_session_v1_TwitterOAuthFactor' embeddable_magic_link_factor: $ref: '#/components/schemas/api_session_v1_EmbeddableMagicLinkFactor' biometric_factor: $ref: '#/components/schemas/api_session_v1_BiometricFactor' saml_sso_factor: $ref: '#/components/schemas/api_session_v1_SAMLSSOFactor' description: Information about the SAML SSO factor, if one is present. oidc_sso_factor: $ref: '#/components/schemas/api_session_v1_OIDCSSOFactor' description: Information about the OIDC SSO factor, if one is present. salesforce_oauth_factor: $ref: '#/components/schemas/api_session_v1_SalesforceOAuthFactor' yahoo_oauth_factor: $ref: '#/components/schemas/api_session_v1_YahooOAuthFactor' hubspot_oauth_factor: $ref: '#/components/schemas/api_session_v1_HubspotOAuthFactor' description: Information about the Hubspot OAuth factor, if one is present. slack_oauth_exchange_factor: $ref: '#/components/schemas/api_session_v1_SlackOAuthExchangeFactor' description: Information about the Slack OAuth Exchange factor, if one is present. hubspot_oauth_exchange_factor: $ref: '#/components/schemas/api_session_v1_HubspotOAuthExchangeFactor' description: Information about the Hubspot OAuth Exchange factor, if one is present. github_oauth_exchange_factor: $ref: '#/components/schemas/api_session_v1_GithubOAuthExchangeFactor' description: Information about the Github OAuth Exchange factor, if one is present. google_oauth_exchange_factor: $ref: '#/components/schemas/api_session_v1_GoogleOAuthExchangeFactor' description: Information about the Google OAuth Exchange factor, if one is present. impersonated_factor: $ref: '#/components/schemas/api_session_v1_ImpersonatedFactor' description: Information about the impersonated factor, if one is present. oauth_access_token_exchange_factor: $ref: '#/components/schemas/api_session_v1_OAuthAccessTokenExchangeFactor' description: Information about the access token exchange factor, if one is present. trusted_auth_token_factor: $ref: '#/components/schemas/api_session_v1_TrustedAuthTokenFactor' description: Information about the trusted auth token factor, if one is present. required: - type - delivery_method api_session_v1_PhoneNumberFactor: type: object properties: phone_id: type: string description: The globally unique UUID of the Member's phone number. phone_number: type: string description: The phone number of the Member. required: - phone_id - phone_number api_session_v1_FigmaOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject api_device_history_v1_DeviceAttributeDetails: type: object properties: is_new: type: boolean description: Whether this `ip_geo_country` has been seen before for this user. first_seen_at: type: string description: 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: type: string description: 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`. required: - is_new api_session_v1_ImpersonatedFactor: type: object properties: impersonator_id: type: string description: For impersonated sessions initiated via the Stytch Dashboard, the `impersonator_id` will be the impersonator's Stytch Dashboard `member_id`. impersonator_email_address: type: string description: The email address of the impersonator. required: - impersonator_id - impersonator_email_address api_session_v1_OIDCSSOFactor: type: object properties: id: type: string description: The unique ID of an SSO Registration. provider_id: type: string description: Globally unique UUID that identifies a specific OIDC Connection. external_id: type: string description: The ID of the member given by the identity provider. required: - id - provider_id - external_id api_session_v1_TikTokOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject 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_session_v1_SnapchatOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject api_session_v1_RecoveryCodeFactor: type: object properties: totp_recovery_code_id: type: string required: - totp_recovery_code_id api_otp_v1_otp_whatsapp_LoginOrCreateResponse: 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. phone_id: type: string description: The unique ID for the phone number. user_created: type: boolean description: In `login_or_create` endpoints, this field indicates whether or not a User was just created. status_code: type: integer format: int32 description: The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors. required: - request_id - user_id - phone_id - user_created - status_code api_otp_v1_otp_sms_SendRequest: type: object properties: phone_number: type: string description: The phone number to use for one-time passcodes. The phone number should be in E.164 format (i.e. +1XXXXXXXXXX). You may use +10000000000 to test this endpoint, see [Testing](https://stytch.com/docs/home#resources_testing) for more detail. expiration_minutes: type: integer format: int32 description: Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes. attributes: $ref: '#/components/schemas/api_attribute_v1_Attributes' description: Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application. locale: $ref: '#/components/schemas/api_otp_v1_SendRequestLocale' description: 'Used to determine which language to use when sending the user this delivery method. Parameter is an [IETF BCP 47 language tag](https://www.w3.org/International/articles/language-tags/), e.g. `"en"`. Currently supported languages are English (`"en"`), Spanish (`"es"`), French (`"fr"`) and Brazilian Portuguese (`"pt-br"`); if no value is provided, the copy defaults to English. Request support for additional languages [here](https://docs.google.com/forms/d/e/1FAIpQLScZSpAu_m2AmLXRT3F3kap-s_mcV6UTBitYn6CdyWP0-o7YjQ/viewform?usp=sf_link")! ' 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. description: Request type required: - phone_number api_session_v1_GithubOAuthExchangeFactor: type: object properties: email_id: type: string description: The globally unique UUID of the Member's email. required: - email_id api_session_v1_LinkedInOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject api_session_v1_CoinbaseOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject api_otp_v1_otp_whatsapp_LoginOrCreateRequest: type: object properties: phone_number: type: string description: The phone number to use for one-time passcodes. The phone number should be in E.164 format (i.e. +1XXXXXXXXXX). You may use +10000000000 to test this endpoint, see [Testing](https://stytch.com/docs/home#resources_testing) for more detail. expiration_minutes: type: integer format: int32 description: Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes. attributes: $ref: '#/components/schemas/api_attribute_v1_Attributes' description: Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application. create_user_as_pending: type: boolean description: "Flag for whether or not to save a user as pending vs active in Stytch. Defaults to false.\n If true, users will be saved with status pending in Stytch's backend until authenticated.\n If false, users will be created as active. An example usage of\n a true flag would be to require users to verify their phone by entering the OTP code before creating\n an account for them." locale: $ref: '#/components/schemas/api_otp_v1_LoginOrCreateRequestLocale' description: 'Used to determine which language to use when sending the user this delivery method. Parameter is an [IETF BCP 47 language tag](https://www.w3.org/International/articles/language-tags/), e.g. `"en"`. Currently supported languages are English (`"en"`), Spanish (`"es"`), French (`"fr"`) and Brazilian Portuguese (`"pt-br"`); if no value is provided, the copy defaults to English. Request support for additional languages [here](https://docs.google.com/forms/d/e/1FAIpQLScZSpAu_m2AmLXRT3F3kap-s_mcV6UTBitYn6CdyWP0-o7YjQ/viewform?usp=sf_link")! ' description: Request type required: - phone_number api_session_v1_InstagramOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject api_otp_v1_otp_whatsapp_SendRequest: type: object properties: phone_number: type: string description: The phone number to use for one-time passcodes. The phone number should be in E.164 format (i.e. +1XXXXXXXXXX). You may use +10000000000 to test this endpoint, see [Testing](https://stytch.com/docs/home#resources_testing) for more detail. expiration_minutes: type: integer format: int32 description: Set the expiration for the one-time passcode, in minutes. The minimum expiration is 1 minute and the maximum is 10 minutes. The default expiration is 2 minutes. attributes: $ref: '#/components/schemas/api_attribute_v1_Attributes' description: Provided attributes to help with fraud detection. These values are pulled and passed into Stytch endpoints by your application. locale: $ref: '#/components/schemas/api_otp_v1_SendRequestLocale' description: 'Used to determine which language to use when sending the user this delivery method. Parameter is an [IETF BCP 47 language tag](https://www.w3.org/International/articles/language-tags/), e.g. `"en"`. Currently supported languages are English (`"en"`), Spanish (`"es"`), French (`"fr"`) and Brazilian Portuguese (`"pt-br"`); if no value is provided, the copy defaults to English. Request support for additional languages [here](https://docs.google.com/forms/d/e/1FAIpQLScZSpAu_m2AmLXRT3F3kap-s_mcV6UTBitYn6CdyWP0-o7YjQ/viewform?usp=sf_link")! ' 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. description: Request type required: - phone_number 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_session_v1_GithubOAuthFactor: type: object properties: id: type: string description: The unique ID of an OAuth registration. 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. email_id: type: string description: The globally unique UUID of the Member's email. required: - id - provider_subject api_session_v1_GoogleOAuthExchangeFactor: type: object properties: email_id: type: string description: The globally unique UUID of the Member's email. required: - email_id api_session_v1_HubspotOAuthExchangeFactor: type: object properties: email_id: type: string description: The globally unique UUID of the Member's email. required: - email_id api_session_v1_WebAuthnFactor: type: object properties: webauthn_registration_id: type: string domain: type: string user_agent: type: string required: - webauthn_registration_id - domain api_otp_v1_LoginOrCreateRequestLocale: type: string enum: - en - es - pt-br - fr api_session_v1_FacebookOAuthFactor: type: object properties: id: type: string provider_subject: type: string email_id: type: string required: - id - provider_subject api_otp_v1_SendRequestLocale: type: string enum: - en - es - pt-br - fr 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_session_v1_BiometricFactor: type: object properties: biometric_registration_id: type: string required: - biometric_registration_id api_session_v1_AuthenticatorAppFactor: type: object properties: totp_id: type: string description: Globally unique UUID that identifies a TOTP instance. required: - totp_id api_session_v1_SlackOAuthExchangeFactor: type: object properties: email_id: type: string description: The globally unique UUID of the Member's email. required: - email_id api_otp_v1_otp_email_LoginOrCreateResponse: 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. email_id: type: string description: The unique ID of a specific email address. user_created: type: boolean description: In `login_or_create` endpoints, this field indicates whether or not a User was just created. status_code: type: integer format: int32 description: The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors. required: - request_id - user_id - email_id - user_created - status_code api_session_v1_MicrosoftOAuthFactor: type: object properties: id: type: string description: The unique ID of an OAuth registration. 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. email_id: type: string description: The globally unique UUID of the Member's email. required: - id - provider_subject securitySchemes: basicAuth: type: http scheme: basic