# CARV ID OAuth 2.0 ## Overview This guide is intended for developers looking to integrate CARV ID authentication into their applications using OAuth 2.0. OAuth 2.0 is a standard for authorization that enables third-party applications to obtain limited access to an HTTP service. By integrating CARV ID OAuth 2.0, users can securely and conveniently log in to your application using their CARV ID credentials. ## Prerequisites Before you begin, ensure you have the following: * A registered application with CARV and your `Client ID` and `Client Secret`. * An understanding of OAuth 2.0 flow. ### Step 1: Register Your Application 1. **Determining Necessary Permissions**: Begin by reviewing the [application scopes available](#scopes) to identify the permissions your application will need. 2. Provide Application Information: Share your application's **Redirect URL** and the **scopes** you've selected based on your needs. Additionally, provide the following information: * **Name Displayed on OAuth Screen**: The name of your application as it will appear during the authentication process. * **Home Page URL**: The main URL of your application, where users can learn more about your service. * **Logo Image URL**: A URL pointing to your logo image, which will be displayed during the authentication process. * **Privacy Policy URL**: The URL of your privacy policy page. * **Terms of Service URL**: The URL of your terms of service page. 3. After we receive this information, we will set up your OAuth configuration and provide you with a Client ID and Client Secret. Keep these confidential. ### Step 2: Implement the OAuth 2.0 Flow {% hint style="info" %} OAuth 2.0 flow at a very high level: * The application renders a “Sign in with CARV ID” link or button. * The user clicks the sign in button. * The current web browser is redirected to CARV (or a new browser is opened and directed to CARV). * The user completes a login and authorization step at CARV if needed. * CARV redirects back to an URL under the application’s control, passing authorization information for the user. {% endhint %} ## API Details **Discover OAuth Information** ```bash curl -X GET https://oauth.carv.io/.well-known/openid-configuration ``` #### Authorization Request Construct and redirect users to the CARV ID authorization page to begin the authentication process: {% code overflow="wrap" %} ```bash https://auth.carv.io/auth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=YOUR_SCOPE&state=YOUR_STATE ``` {% endcode %} Parameters: * `response_type`: Should be `code` for the authorization code flow. * `client_id`: Your application's Client ID. * `redirect_uri`: The URL to which CARV ID will send the user after authorization. * `scope`: The space-separated list of permissions your application requests. * `state`: A unique state value that your application generates to mitigate CSRF attacks. After successful login and authorization, user will be redirected to the provided URL with `code` and `state` included in the parameters. #### **Scopes** Scopes allow you to set granular access for your application so that your application only has the permissions that it needs.
ScopeDescription
carv_id_basic_readBasic CARV ID info
email_basic_readEmail address
twitter_basic_readBasic Twitter account info
discord_basic_readBasic Discord account info
facebook_basic_readBasic Facebook account info
google_basic_readBasic Google account info
steam_basic_readBasic Steam account info
steam_detailed_readDetailed Steam account info
carv_play_basic_readBasic CARV Play account info
evm_address_basic_readEVM address
solana_address_basic_readSolana address
bitcoin_address_basic_readBitcoin address
platform_detailed_readUser's account info from your platform/application/game
platform_detailed_writeUpdate user's account info from your platform/application/game to CARV ID
#### Access Token Request After the user authorizes your application, they will be redirected to your `redirect_uri` with a `code` parameter. Exchange this code for an access token. ```bash curl -X POST https://oauth.carv.io/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -H "Authorization: Basic YOUR_BASE64_ENCODED_CLIENT_ID_AND_SECRET" \ -d "grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=YOUR_REDIRECT_URI" ``` Parameters: * `grant_type`: Should be `authorization_code`. * `code`: The authorization code received from the authorization request. * `redirect_uri`: Must match the redirect URI used in the authorization request. * `client_id`: Your application's Client ID. * `client_secret`: Your application's Client Secret. Sample Python code to encode credentials: ```python import base64 # Your client ID and client secret client_id = 'your_client_id_here' client_secret = 'your_client_secret_here' # Concatenate the client ID and client secret with a colon credentials = f"{client_id}:{client_secret}" # Encode the credentials using base64 encoded_credentials = base64.b64encode(credentials.encode()).decode() # The result can be used in the Authorization header print("Basic " + encoded_credentials) ``` Response Sample ```json { "code": 0, "msg": "", "data": { "access_token": "xxxx", "token_type": "Bearer", "expires_in": "604800", "scope": "xxxx", "refresh_token": "xxxx", "id_token": "xxxx" } } ``` #### Token Refresh Request Refresh an expired access token using: ```bash curl -X POST https://oauth.carv.io/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -H "Authorization: Basic YOUR_BASE64_ENCODED_CLIENT_ID_AND_SECRET" \ -d "grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN&scope=YOUR_SCOPE" ``` Parameters: * `grant_type`: Should be `refresh_token`. * `refresh_token`: The `refresh_code` received from the access token request. * `scope`: The space-separated list of permissions your application requests. * `client_id`: Your application's Client ID. * `client_secret`: Your application's Client Secret. Response Sample ```json { "code": 0, "msg": "", "data": { "access_token": "xxxx", "token_type": "Bearer", "expires_in": "604800", "scope": "xxxx", "refresh_token": "xxxx", "id_token": "xxxx" } } ``` #### Fetch User Detailed Info Retrieve detailed user information with: ```bash curl -X GET https://oauth.carv.io/api/userinfo \ -H "Authorization: Bearer ACCESS_TOKEN" ``` Response Sample ```json { "code": 0, "msg": "", "data": { "smart_wallet_address": "xxxx", "signer_wallet_address": "xxxx", "email_address": "abc@gmail.com", "twitter": { "id": "xxxx", "username": "xxxx" } // Additional fields } } ``` #### Update User Profile Third-party data providers can update the user's profile data via: ```bash curl -X POST https://oauth.carv.io/api/userinfo/update \ -H "Content-Type: application/x-www-form-urlencoded" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -d "user_id=xxx&user_name=xxx&properties={}" ``` Parameters: * `user_id`: The unique identifier for the user on the third-party platform. * `user_name`: The name of the user on the third-party platform. * `properties`: A JSON formatted string containing any additional property data to upload. Note that to use this API, you will need to apply for the write access scope for the platform. ## Conclusion This guide outlines the process for securely integrating CARV ID OAuth 2.0 into your applications, enhancing user authentication experiences.