> For the complete documentation index, see [llms.txt](https://docs.cotter.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cotter.app/sdk-reference/web/web-sdk-passwordless-login/advanced-customization.md). # Advanced Customization for Login Form ## Configuration Reference Here's an example of a complete configuration: ```javascript var config = { // Required Basic Configuration ApiKeyID: "", Type: "PHONE", ContainerID: "cotter-container-login", RedirectURL: "https://yourwebsite.com/account/create", IdentifierField: "phone", OnSuccess: payload => { window.localStorage.setItem("session", payload.session); window.location.href = "/dashboard"; } OnBegin: async payload => { var userID = await this.getUserIDFromPhone(payload.identifier); return { userID: userID, err: null }; }, // --------- // Change Country Code CountryCode: ["+62"], // IT HAS TO BE AN ARRAY // Styling ButtonBackgroundColor: "#000000", ButtonTextColor: "#ffffff", ButtonText: "Sign Up Now", ErrorColor: "#ff0000", // Event Name in the Event Response EventName: "LOGIN_EMPLOYEE", // Allow OTP as a fallback method for TrustedDevice AllowOTPFallback: true, // Skipping RedirectURL and receive event response in OnSuccess SkipRedirectURL: true, // Change the prompt message AuthRequestText: { title: "Approve this login from your phone", subtitle: "A notification is sent to your trusted device to confirm it's you", image: "https://yourwebsite.com/image.png", titleError: "Something went wrong", subtitleError: "We are unable to confirm it's you, please try again", imageError: "https://yourwebsite.com/image.png", imageSuccess: "https://yourwebsite.com/image.png", switchOTPText: "Authenticate with OTP instead" }, // Receive error message OnError: payload => { console.log("ERROR", payload); } }; ``` ## **Description** | Field Name | Description | Required | | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | ApiKeyID | your `API_KEY_ID` | Y | | [RedirectURL](/sdk-reference/web/web-sdk-verify-email-phone.md#redirecturl) | The backend URL where we will send a [JSON obj](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization.md#redirecturl) containing form information and a token | Y | | Type | `"EMAIL"` or `"PHONE"` | Y | | ContainerID | `id` of the `
` where you want to serve Cotter Form. | Y | | [OnBegin](/sdk-reference/web/web-sdk-verify-email-phone.md#onbegin) | A function that will be called before the login process begin. Return UserID and error if applicable. Check the specs for [OnBegin](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization.md#onbegin) below. | Y | | [SkipRedirectURL](/sdk-reference/web/web-sdk-verify-email-phone/older-sdk/advanced-customization.md#skip-redirecturl) | `true` or `false` . If set to `true`, then it will skip sending the [JSON obj](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization.md#redirecturl) to the RedirectURL, and instead automatically pass it to [`OnSuccess`](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization.md#onsuccess). | N | | ButtonBackgroundColor | Button background color. Use HEX format (e.g. `#000000`) | N | | ButtonTextColor | Button text color. Use HEX format (e.g. `#FFFFFF`) | N | | ButtonText | Button text. Default is "Sign Up Without Password" | N | | ErrorColor | Text color for error messages. Use HEX format (e.g. `#FFFFFF`) | N | | EventName | Tag this authentication event with a name, like `WITHDRAWAL` to make it easier to segment your event logs. | N | | IdentifierField | Field name for the identifier to include in the JSON obj. For example, if you want to include the phone number in the JSON obj under key `"phone"`, then fill in `IdentifierField = "phone"` | Y | | AllowOTPFallback | Allow user to choose to authenticate using OTP (One-Time-Password) instead of Trusted Device if they want. | N | | [OnSuccess](/sdk-reference/web/web-sdk-verify-email-phone.md#onsuccess) | A function that will be called when the signup process succeed. It's recommended to set your localStorage/cookies here and redirect to your dashboard. Check the specs for [OnSuccess](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization.md#onsuccess) below | Y | | [CountryCode](/sdk-reference/web/web-sdk-verify-email-phone.md#countrycode) | **An Array** of country code options for the user | N | | AuthRequestText | A dictionary to customize the text in the authentication prompt | N | | OnError | A function that will be called if there's an error, and will receive the error message or object | N | ### **RedirectURL** We will send a JSON Object to this backend URL. The JSON Object will have the following format: ```javascript { "ID": 2397, "CreatedAt": "2020-04-01T05:28:12.540127Z", "UpdatedAt": "2020-04-01T05:28:16.599833Z", "DeletedAt": null, "client_user_id": "", "issuer": "", "event": "LOGIN_WEB", "ip": "123.347.26.236", "location": "San Mateo", "timestamp": "1585718892", "method": "TRUSTED_DEVICE", "new": false, "approved": true, "signature": "reBafVsmpxO7km5jpRQ3xA..." } ``` Description: **payload.client\_user\_id** Contains your user's `user_id` that you used when registering the user to Cotter. This should be the `user_id` from your backend. **payload.event** The event tag that you specified. The default value is `LOGIN_WEB`. You should specify this with a relevant tag, like `WITHDRAW` ,`PAYMENT` ,etc. You can specify it using the `EventName` attribute in the config. **Validate the event response** You should validate the event response to make sure it comes from Cotter's server {% content-ref url="/pages/-M2pWffm56vOPZk07RZ7" %} [Validating Cotter's Event Response](/older-api/validating-cotters-event-response.md) {% endcontent-ref %} ### Skip RedirectURL If you want to handle Cotter's Event Response in a function instead of sending it to your backend `redirect_url`, you can specify ```javascript { ... SkipRedirectURL: true, } ``` When this is true, the [JSON payload](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization.md#redirecturl) as specified in RedirectURL section will be passed into your [OnSuccess](/sdk-reference/web/web-sdk-passwordless-login/advanced-customization.md#onsuccess) function. ### **OnBegin** This function will be invoked before the Login process. **You are expected to return a `user_id` at the end of the function**. You will receive the following payload as a parameter to your function **Payload passed into your OnBegin function** ```javascript var payload = { identifier: "+12345678910", identifier_type: "PHONE", device_type: "BROWSER", device_name: "Chrome ..." }; ``` 1. You can do a check against the `identifier` here before the form is submitted. 2. You should get the `user_id` based on the identifier in your backend (or use the identifier if that's what you used). This should be the same as the user id used in the [Required Steps.](/sdk-reference/web/web-sdk-passwordless-login.md#step-2-creating-a-user) **A. If there is no error:** ```javascript return { userID: "", err: null, } ``` **B. If there is an error:** ```javascript return { userID: "anything", err: "Error message", } ``` Example: ```javascript OnBegin: payload => { if (payload.identifier != "+12345678910") { return { userID: null, err: "Phone Number is not allowed", } } // No error, continue submission var userID = this.getUserIDFromPhone(payload.identifier); return { userID: userID, err: null, }; }, ``` ### **OnSuccess** This function will be called **after** the call to `RedirectURL` is successful. Your function will receive the payload returned from `RedirectURL`. It is recommended to set your sessions or cookies here, and then redirect to another page in your website. For example: ```javascript OnSuccess: payload => { // You can set your own sessions for your website window.localStorage.setItem("access_token", payload.access_token); window.localStorage.setItem("refresh_token", payload.refresh_token); window.location.href = "/dashboard"; }; ``` **OnSuccess when SkipRedirectURL is true** When you set `SkipRedirectURL: true` , `OnSuccess` will instead receive the JSON Event REsponse that was described in RedirectURL section. ### **CountryCode** The default value is `CountryCode: ["+1"];` {% hint style="warning" %} If you specify this, **you have to use an array** even though you only need 1 country code! {% endhint %} ex. with 1 country code ```javascript CountryCode: ["+1"]; ``` ex. with 2 country codes ```javascript CountryCode: ["+62", "+91"]; ``` {% hint style="info" %} Currently, the only available countries are **United States**, **India** and **Indonesia**. Chat us on Intercom if you need other countries, we just need to switch it on. {% endhint %} ### AllowOTPFallback If you set this to true, your users will have the option to use OTP to login/authenticate. You should set OTP Fallback as true in your dashboard under Rules. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cotter.app/sdk-reference/web/web-sdk-passwordless-login/advanced-customization.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.