Manual Integration

If you're not using an auth framework, you'll need to implement the OAuth 2.0 flow manually:

OAuth Flow

The ARES OAuth 2.0 flow follows these steps:

1. Your application redirects the user to ARES's authorization endpoint.

2. The user logs in to ARES and grants permission to your application.

3. ARES redirects back to your application with an authorization code.

E.g. If your redirect_uri is set to "www.example.com", the redirection will be to "www.example.com/?code=authorization_code_here&state=state"

1. Your application exchanges the authorization code for an access token.

2. Your application uses the access token to make API calls to ARES on behalf of the user.

OAuth Endpoints:

Authorization endpoint: https://joinares.com/oauth

Token Endpoint: https://oauth.joinares.com/oauth/token

User Endpoint: https://oauth.joinares.com/v1/user

1. Redirect users to the ARES authorization URL

REQUIRED: Replace ARES_CLIENT_ID, ARES_CLIENT_SECRET, and REDIRECT_URI with your credentials.

https://joinares.com/oauth?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code&
  scope=read+write

This redirection will send your user to log in on the ARES website and grant consent for your application to access their information. Once all that is done, the user will be redirected back to your website based on the redirect URI you provided along with the authorization code.

E.g. If your redirect_uri is set to "www.example.com", the redirection will be to "www.example.com/?code=authorization_code_here&state=state"

2. Handle the callback and exchange the authorization code for an access token

After the user authorizes your application, you'll receive an authorization code. The next step is to handle the authorization code that you receive from part 1 and exchange it for an access token.

POST https://oauth.joinares.com/oauth/token

Request Headers

Content-Type: application/x-www-form-urlencoded   

Request Body

grant_type: "authorization_code",
code: AUTH_CODE, // Replace with the code you received from part 1
redirect_uri: REDIRECT_URI, // Replace with your redirect uri
client_id: ARES_CLIENT_ID, // Replace with your client ID
client_secret: ARES_CLIENT_SECRET // Replace with your client secret

• Keep your client_secret confidential. Never expose it in client-side code or public repositories.

• The authorization code can only be used once. If you need to get a new access token later, use the refresh token flow.

• Store the refresh_token securely. You'll need it to obtain new access tokens when the current one expires.

Response

If the request is successful, you'll receive a JSON response containing the access token, refresh token, and other details:

{
  access_token: ACCESS_TOKEN,
  token_type: 'Bearer',
  expires_in: 3599,
  refresh_token: REFRESH_TOKEN
}

Example

Example Fetch Request

// Example Fetch in TypeScript
const tokenResponse = await fetch("http://oauth.joinares.com/oauth/token", {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
      },
      body: new URLSearchParams({
        grant_type: "authorization_code",
        code: code,
        redirect_uri: "https://example.com/auth/callback",
        client_id: "1234",
        client_secret: "5678",
      }).toString(),
    });
const tokenData = await tokenResponse.json();

Example Response

3. Store the access token securely to use it for subsequent API calls.

After receiving the access token, you must store it securely for use in subsequent API calls. The method of storage depends on your application type and security requirements.

Important Considerations:

1. Security: Store the access token in a secure manner to prevent unauthorized access.

2. Application Type:

   • For server-side applications, consider using secure server-side storage solutions.

   • For client-side applications, use secure storage mechanisms provided by the platform.

3. Encryption: If storing the token locally, consider encrypting it.

4. Token Lifespan: Remember that access tokens are typically short-lived. Implement proper token refresh mechanisms.

5. Usage: When making API calls, include the access token in the Authorization header:

   Authorization: Bearer YOUR_ACCESS_TOKEN

6. Compliance: Ensure your storage method complies with relevant security standards and regulations.

The specific implementation of token storage is up to you and should be tailored to your application's architecture and security requirements. Always prioritize the security of your users' data and follow best practices for your chosen platform and technology stack.

4. Refresh the access token

Refresh token URL: https://oauth.joinares.com/oauth/token

Access tokens are designed to be short-lived for security reasons. When an access token expires (1 hour after issuance in our case), instead of requiring the user to log in again, you can use a refresh token to obtain a new access token.

When you initially authenticate, you receive both an access token and a refresh token (example)

To refresh your access token:

1. Send a POST request to the token endpoint.

2. Use the refresh_token grant type.

3. Include your refresh token in the request body.

Example request:

POST https://oauth.joinares.com/oauth/token

Content-Type: application/x-www-form-urlencoded 

{
  "client_id": YOUR_CLIENT_ID,
  "client_secret": YOUR_CLIENT_SECRET,
  "grant_type": "refresh_token",
  "refresh_token": YOUR_REFRESH_TOKEN,
  "redirect_uri": YOUR_REDIRECT_URI
}

This will return a new access token and refresh token pair. Always use the most recent refresh token for subsequent refresh requests.

Example response:

Note: Refresh tokens may also expire. If this happens, you'll need to re-authenticate the user through the full OAuth flow.

{
  "access_token": "139e459199161d1b43a051bf5ad353afaace3a69",
  "token_type": "Bearer",
  "expires_in": 3599,
  "refresh_token": "8c6e65c0a49a9c113134975a44230ad151713b47"
}