API Endpoints

API Endpoints

• User Info URL: https://oauth.joinares.com/v1/user

• Usage tracking URL: https://oauth.joinares.com/v1/partner/usage

For the authorization / access code endpoints, please refer to Manual Integration

---

User Info Endpoint

The user info endpoint is used to retrieve the user object, which includes the user's id, email, and credits left.

This endpoint requires an access token that you received from the OAuth process. Each token has a specific user tied to it. URL: https://oauth.joinares.com/v1/user

Method: GET

Headers (example)

Name	Required	Description
Authorization	Yes	Bearer token for authentication. Replace USER_ACCESS_TOKEN with an actual access token.

Response (example)

200 OK

A successful response will return a JSON object containing user information.

{
  "message": "Success",
  "user": {
    "id": "f7ef2d60-2d1d-4afc-a510-f965e75a4b15",
    "email": "[e-mail]",
    "credits": 698
  }
}

Response Fields

Field	Type	Description
message	string	Retrieval status. "Success" if successful.
user	object	The user object.
user.id	string	Unique Identifier for the user.
user.email	string	User's email.
user.credits	number	Number of ARES credits the user has left.

Error Responses

401 Unauthorized

There are a few possible reasons for 401 Unauthorized response:

{
  "error": "No token provided" // Token not detected in the auth header
},

{
  "error": "Invalid token" // Token doesn't exist or is expired. 
}                          // If token is expired, try refreshing the token 

403 Forbidden

This happens when the access token is expired. Check how to refresh access token.

{
  "error": "Token expired"
}

Examples

Example Request

Example Fetch request in JavaScript:

// IMPORTANT: Must always include the access token at the header.  
// Fetch request in Javascript
fetch('https://oauth.joinares.com/v1/user', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`, // Required access token in header
    'Content-Type': 'application/json'

  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Alternatively, here's an example HTTP GET request:

POST https://oauth.joinares.com/v1/user
Authorization: Bearer USER_ACCESS_TOKEN // Replace with the real access token

Example Response

---

Usage Tracking Endpoint

This endpoint is used for tracking a user's usage on your platform.

This should be called right before you allow the user to use your tool to deduct the user's ARES credit and tracks to usage to your account.

Will return an error if the user doesn't have enough credits.

URL: https://joinares.com/v1/partner/usage

Method: POST

Quick links: Headers, Body, Response, Errors

Headers (example)

Name	Required	Description
Authorization	Yes	Bearer token for authentication. Replace USER_ACCESS_TOKEN with an actual access token.
Content-Type	Yes	Use the value application/json to specify that the body is in JSON format.

Body (example)

Name	Required	Type	Description
client_id	Yes	string	Your client ID
usage	Yes	string	A short note/description on what the usage is about. This should stay consistent with each usage if it's on the same thing. (Ex. "video generation", "editing 1 video", etc.) Line Item.
credits	Yes	number	The number of credits to deduct from the user's ARES account for this usage.

There's no need to include additional information about the user because we will take that information from the access token in the header.

Response (example)

200 OK

A successful response will return a JSON like the following:

{
  "message": "Success",
  "usage": {
    "usage_timestamp": "2024-08-02T23:59:34.814597+00:00",
    "user_id": USER'S USER ID,
    "client_id": YOUR CLIENT ID,
    "credits_earned": CREDITS USED,
    "usage": USAGE REASON
  }
}

Response Fields

Field	Type	Description
message	string	Status message. Returns "Success" if successful.
usage	object	Contains information about the usage for confirmation.
usage.usage_timestamp	timestamp with timezone	Time when the usage is logged.
usage.user_id	string	The user id of the user.
usage.client_id	string	Your client id.
usage.credits_earned	number	Credits the user spend / you earned.
usage.usage	string	Reason for the usage.

Error Responses

400 Missing Required Parameters

One or more parameters is missing.

401 Unauthorized

There are 2 reasons why this error is returned:

1. No access token provided in the header.

{
  "error": "No token provided"
}

1. Token/client id mismatch.

{
  "error": "Token/client id mismatch."
}

402 Payment Required

User does not have enough credits.

{
  "error": "Insufficient credits."
}

403 Forbidden

This happens when the access token is expired. Check how to refresh access token.

{
  "error": "Token expired"
}

Examples

Example Request

Example Fetch Request In Javascript:

// IMPORTANT: Must always include the access token at the header.  
const accessToken = 'USER_ACCESS_TOKEN'; // Replace this value

// Fetch request in Javascript
fetch('https://oauth.joinares.com/v1/partner/usage', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`, // Required access token in header
    'Content-Type': 'application/json'
  },
 body: JSON.stringify({
    "client_id": ARES_CLIENT_ID, // Replace with your client ID
    "usage": USAGE_INFO, // Replace with a note on what the user is trying to use
    "credits": NUMBER_OF_CREDITS // Replace with the number of credits the usage will cost the user
  })
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Alternatively, here's an example HTTP POST request:

POST https://oauth.joinares.com/v1/partner/usage
Authorization: Bearer ${accessToken}  //Replace with actual token
Content-Type: application/json

{
    "client_id": ARES_CLIENT_ID, // Replace with your client ID
    "usage": USAGE_INFO, // Replace with a note on what the user is trying to use
    "credits": NUMBER_OF_CREDITS // Replace with the number of credits the usage will cost the user
}

Example Response