# 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](/getting-access-token/renewing-expired-tokens.md). 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="/pages/-M4HZPVawEx2QN3qLmnv" %} [Verifying JWT Tokens](/getting-access-token/verifying-jwt-tokens.md) {% 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](/getting-access-token/renewing-expired-tokens.md). {% 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](/getting-access-token/renewing-expired-tokens.md). ``` 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="/pages/-M4HcAeSw6KbuSrnge2U" %} [Getting the Tokens](/getting-access-token/getting-the-tokens.md) {% 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="/pages/-M4I5Ed9v0BbC7OxzSFn" %} [Storing and Removing Tokens](/getting-access-token/storing-and-removing-tokens.md) {% 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="/pages/-M4I0B0i0yghkR8yjphX" %} [Renewing Expired Tokens](/getting-access-token/renewing-expired-tokens.md) {% 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="/pages/-M4HZPVawEx2QN3qLmnv" %} [Verifying JWT Tokens](/getting-access-token/verifying-jwt-tokens.md) {% 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="/pages/-MGMZEOXjRRPxy1zAe-9" %} [Requesting Custom Claims on your Access Token](/api-reference/oauth-tokens-api/requesting-custom-claims-on-your-access-token.md) {% endcontent-ref %} ## πŸŽ‰ You're done! --- # Agent Instructions: 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/getting-access-token/handling-authentication-with-cotter.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.