# Cotter's OAuth 2.0 Tokens Specification ## Handling Authentication After successful authentication, Cotter returns ID, access, and refresh tokens as defined by the OpenID Connect (OIDC) open standard: * The [ID Token](http://openid.net/specs/openid-connect-core-1_0.html#IDToken) contains information about the authenticated user such as email , phone number , `client_user_id` (the user's id in your server), and `auth_time` (last authenticated time). * The [Access Token](https://tools.ietf.org/html/rfc6749#section-1.4) contains scopes and the authentication method used to authenticate the user: `OTP`, `TRUSTED DEVICE` , `PIN` or `BIOMETRIC` . * The [Refresh Token](https://tools.ietf.org/html/rfc6749#section-1.5) contains the information necessary to obtain a new ID and access token. {% hint style="warning" %} πŸ”’It is important to **secure all tokens** in transit and storage. {% endhint %} ## Client Libraries Currently, we have the following libraries available to handle Cotter's OAuth Tokens: * Cotter Token JS for Decoding JWT Tokens: [`cotter-token-js`](https://github.com/cotterapp/cotter-token-js) * Cotter Node for validating JWT Tokens in your server: [`cotter-node`](https://github.com/cotterapp/cotter-node-js) ## Cotter's Access Token Cotter's Access token is a [JSON Web Tokens (JWTs)](https://jwt.io/) that is used to tell your backend API that the user has been authorized to call the API and perform some action (defined in the `scopes` attribute of the token). Access tokens expires every 1 hour. [Check the guide on renewing access and id tokens](https://docs.cotter.app/getting-access-token/renewing-expired-tokens). Token example: {% tabs %} {% tab title="Access Token" %} ```javascript eyJhbGciOiJFUzI1NiIsImtpZCI6IlNQQUNFX0pXVF9QVU... ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Example decoded token" %} ```javascript { "sub": "09efb1b-e50f-41fd-8530-88ffbcd80f59", // [Deprecated] Cotter's User id "client_user_id": "09efb1b-e50f-41fd-8530-88ffbcd80f59", // deprecated "authentication_method": "TRUSTED_DEVICE", // How the user is authenticated "type": "access_token", "identifier": "putri@cotter.app", // User's email or phone number "scope": "access", // Scope of this access token (coming soon) "aud": "", // Your API_KEY_ID "exp": 1586231136, // Expires at "iat": 1586227536, // Issued at "jti": "47fba8ba-abcd-efgh-a22c-a2b8b72e8b98", "iss": "https://www.cotter.app" } ``` {% endtab %} {% endtabs %} ### How to use the Access Token to allow API calls 1\. On every API call to your server, attach the access token as a header ``` Authorization: Bearer ``` 2\. In your server, using a middleware, check if the access token is valid {% content-ref url="verifying-jwt-tokens" %} [verifying-jwt-tokens](https://docs.cotter.app/getting-access-token/verifying-jwt-tokens) {% endcontent-ref %} 3\. If the access token is valid, allow the API call to proceed. ## Cotter's ID Token Cotter's ID token is a [JSON Web Tokens (JWTs)](https://jwt.io/) that is used to provide information about the user. ID tokens expires every 1 hour. [Check the guide on renewing access and id tokens](https://docs.cotter.app/getting-access-token/renewing-expired-tokens). {% tabs %} {% tab title="Example Decoded Token" %} ```javascript { "sub": "43e53999-c31e-4ed9-a196-71031a05f297", // [Deprecated] Cotter User ID "client_user_id": "43e53999-c31e-4ed9-a196-71031a05f297", // Deprecated "auth_time": "1591756112", // Last authenticated time (Unix timestamp) "identifier": "putri@cotter.app", "type": "id_token", "aud": "", // your API KEY ID "exp": 1586232181, // Expires at "iat": 1586228581, // Issued at "jti": "886773db-abcd-efgh-aefc-6ab481b24099", "iss": "https://www.cotter.app" } ``` {% endtab %} {% endtabs %} {% hint style="info" %} You should not trust this information after it's expired {% endhint %} ## Cotter's Refresh Token Cotter's Refresh Token is an opaque token (i.e. a random string) that is used to generate a new `access token` and `id token` when they're expired. Refresh tokens expires every 30 days. You need to re-authenticate the user to get a new refresh token. [Check the guide on renewing access and id tokens](https://docs.cotter.app/getting-access-token/renewing-expired-tokens). ``` 14:Pmw3r3rgaw0rLupUDU4hjwJFisv8EaHRaoy5gw54ZmSebaWHDh ``` ## πŸ₯³ Getting Started ### 1. Getting The Tokens using the SDK Easily get tokens using the SDK by adding a simple paramater, ex. `getOAuthToken = true` {% content-ref url="getting-the-tokens" %} [getting-the-tokens](https://docs.cotter.app/getting-access-token/getting-the-tokens) {% endcontent-ref %} ### 2. Storing & Removing the Token The SDK generally automatically store tokens securely for you, and provides a function to easily remove the tokens to logout your users. {% content-ref url="storing-and-removing-tokens" %} [storing-and-removing-tokens](https://docs.cotter.app/getting-access-token/storing-and-removing-tokens) {% endcontent-ref %} ### 3. Renewing Expired Tokens The SDK generally automatically renews expired `access_token` and `id_token` whenever a valid `refresh_token` exists. {% content-ref url="renewing-expired-tokens" %} [renewing-expired-tokens](https://docs.cotter.app/getting-access-token/renewing-expired-tokens) {% endcontent-ref %} ### 4. Verifying the Tokens You need to verify the JWT tokens in your backend server. Fortunately, there are a lot of good libraries that do this. {% content-ref url="verifying-jwt-tokens" %} [verifying-jwt-tokens](https://docs.cotter.app/getting-access-token/verifying-jwt-tokens) {% endcontent-ref %} ### 5. Adding Custom Claims to your JWT Token If you have additional metadata from your backend server that you'd like to add to the JWT token (for example, the user's `role` or `name`, you can call Cotter's API to add the claims to Cotter's JWT token {% content-ref url="../api-reference/oauth-tokens-api/requesting-custom-claims-on-your-access-token" %} [requesting-custom-claims-on-your-access-token](https://docs.cotter.app/api-reference/oauth-tokens-api/requesting-custom-claims-on-your-access-token) {% endcontent-ref %} ## πŸŽ‰ You're done!