Authentication API that can be called from your mobile apps. This API utilizes an in-app webview with cookies sharing to allow a single-sign-on for bypassing email and phone number verification.
Mobile apps can't securely store the Secret Key. This is because decompiling the App will reveal the Secret Key, and there's only one secret key so it'll be the same for all users.
Sending tokens to Custom URL schemes (ex. YourApp://) will potentially expose the tokens to malicious apps.
Request Authorization from Cotter: Redirect user to Cotter to verify their email/phone and receive an authorization_code back to your app.
Request Tokens and Identity: Send your authorization_code and code_verifier to Cotter server and get back a token and the user's email or phone number.
Include Token to your server: The token contains the user's verified email/phone number and a signature. Include this to your signup/login request to your backend
Step 1: Create a Code Verifier
A code_verifier is a cryptographically-random key that will be sent to Cotter along with the authorization_code on Step 3. Read more about what are code challenge and verifier.
The code_challenge is sent first so that later in step 3, Cotter's server can verify that hash(code_verifier) is the same as code_challenge and that you are indeed made the original request.
Checking your code challenge and verifier
To check if your code_challenge and code_verifier are correctly generated and formatted, try comparing it with codes generated here https://example-app.com/pkce
Step 2: Request Authorization from Cotter
Open Cotter's Auth URL from a WebView from your app.
A random string that you generate from your application before opening to Cotter's Auth (ex. abcXYZ456). This is not the same as your code_verifier. You need to check if the state included by Cotter in the redirect_url is the same as the initial state that you set to make sure the request is for you. Learn more about state.
Make sure the scheme of your redirect_url (the front part before ://) doesn't have an underscore or other special characters. To test it out, enter your redirect_url here: https://jsfiddle.net/omd02jn5/
Here's an example on opening the in-app Browser from iOS and Android
In this step, you'll use your code_verifier , authorization_code and the challenge_id to request tokens and the user's email or phone number from Cotter's server.
Your authorization_token is valid for 5 minutes, and can only be used once.
Now that the email or phone number is verified, you can continue your Sign Up or Login process by submitting the email or phone number to your server, either now or after the user enters more information.
You should include this oauth_tokens into your call to your backend for Login or Registration. Your backend should then verify that the access token is valid.
Validating Cotter's Access Token
Check out how to verify the OAuth Tokens from Cotter here:
Since you'll be using your API Key from a front-end website or mobile app, your API_KEY_ID is exposed to anyone inspecting your code. Here are some ways to prevent abuse:
Your app generates state=XYZ in the beginning of the auth flow. You should expect that Cotter's response on Step 2 when Cotter redirect back to your redirect_url, the state is the same (state == XYZ). This makes sure that the redirect was in response to your initial authentication request.
code_challenge / verifier:
This is needed for installed apps / SPA because they cannot store the Api Secret Key securely, so the code_challenge and code_verifier is for Cotter to make sure that the original App that requested authentication on Step 2 is the same as the one that asked for access token on Step 3.