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
andClient Secret
.An understanding of OAuth 2.0 flow.
Step 1: Register Your Application
Determining Necessary Permissions: Begin by reviewing the application scopes available to identify the permissions your application will need.
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.
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
API Details
Discover OAuth Information
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:
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
Parameters:
response_type
: Should becode
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.
carv_id_basic_read
Basic CARV ID info
email_basic_read
Email address
twitter_basic_read
Basic Twitter account info
discord_basic_read
Basic Discord account info
facebook_basic_read
Basic Facebook account info
google_basic_read
Basic Google account info
steam_basic_read
Basic Steam account info
steam_detailed_read
Detailed Steam account info
carv_play_basic_read
Basic CARV Play account info
evm_address_basic_read
EVM address
solana_address_basic_read
Solana address
bitcoin_address_basic_read
Bitcoin address
platform_detailed_read
User's account info from your platform/application/game
platform_detailed_write
Update 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.
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 beauthorization_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:
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
{
"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:
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 berefresh_token
.refresh_token
: Therefresh_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
{
"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:
curl -X GET https://oauth.carv.io/api/userinfo \
-H "Authorization: Bearer ACCESS_TOKEN"
Response Sample
{
"code": 0,
"msg": "",
"data": {
"smart_wallet_address": "xxxx",
"signer_wallet_address": "xxxx",
"email_address": "[email protected]",
"twitter": {
"id": "xxxx",
"username": "xxxx"
}
// Additional fields
}
}
Update User Profile
Third-party data providers can update the user's profile data via:
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.
Last updated