Authentication

All calls to AgentSync APIs require a valid access token obtained through the OAuth 2.0 Client Credentials flow.

Overview

As part of the Client Credentials flow:

1. Your client authenticates with AgentSync's authorization server using securely provided credentials
2. If valid, the server issues an access token
3. This token is then used to authenticate all subsequent API requests
4. The issued token will remain valid for a limited time and should be reused until expiration

⚠️ Security Notice: We hold the highest standards for data privacy and security. We expect that developers using our APIs follow secure practices when integrating with us including, but not limited to, (i) accessing APIs through secure communication channels and (ii) following security best practices when storing, sharing and accessing API credentials and access tokens.

You must promptly notify us about any known or suspected security incidents. We reserve the right to suspend or deactivate clients whose credentials we suspect have been breached.

Requesting API Access

API access is not self-service at this time. Please contact support@agentsync.io to:

• Request new API keys
• Rotate or revoke existing credentials

Upon approval, you will securely receive your:

• client_id
• client_secret
• scope (if applicable)

These credentials are used to retrieve an access token.

Token Endpoints

Choose the appropriate environment:

Authentication vs API Base URLs

After obtaining your access token from the authentication endpoints above, all subsequent API requests must use the appropriate API base URLs for your environment.

Important: Do not send API calls to the auth.* domain — that is only for obtaining tokens.

Token Retrieval

Request Type: POST

Required Parameters

⚠️ If your request fails with "access_denied" and "Policy evaluation failed", you likely need to include a required scope.

Sample Token Request (cURL)

curl --request POST \
  --url {{TOKEN_ENDPOINT}} \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id={{CLIENT_ID}} \
  --data client_secret={{CLIENT_SECRET}} \
  --data scope={{REQUIRED_SCOPE}}

Sample Token Responses

200 Success

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "xyz123",
  "scope": "https://api.agentsync.io/a_valid_scope"
}

401 Unauthorized - invalid (or no) credentials provided

{
    "errorCode": "invalid_client",
    "errorSummary": "Invalid value for 'client_id' parameter.",
    "errorLink": "invalid_client",
    "errorId": "oaeKUn1hFVRReCw-7SeCP3j7g",
    "errorCauses": []
}

See API Status Codes for a comprehensive list of expected errors.

Authenticating API Requests

Use the retrieved token to call AgentSync APIs:

curl --location 'https://api.agentsync.io/v1/{endpoint}' \
  --header 'Authorization: Bearer {{access_token}}'

Rate Limiting

The token endpoint is rate-limited to 200 requests per minute.

See Rate Limiting to learn more.

Token Expiration & Reuse

Tokens are valid for 60 minutes. You should reuse the token during this window.

Recommended Strategies

Retry on 401 Catch 401 Unauthorized, then request a new token.

Preemptive refresh Track the expiration by adding expires_in to the time the token was received. Refresh before expiration.

⚠️ Avoid requesting a new token on every API call. This increases latency and may trigger rate limits.

Token Reuse Pseudocode

1. Import required libraries:
   • HTTP client (e.g., requests)
   • Time utilities (e.g., datetime)
2. Define constants:
   • CLIENT_ID
   • CLIENT_SECRET
   • TOKEN_URL
3. Initialize variables:
   • access_token = null
   • expiry_time = null
4. Define get_new_token(): a. Send a POST request to TOKEN_URL with:
   • grant_type = client_credentials
   • client_id
   • client_secret b. On success:
   • Extract access_token from response
   • Extract expires_in (in seconds)
   • Set expiry_time = current time + expires_in
5. Define is_token_expired():
   • Return true if current time >= expiry_time
   • Otherwise, return false
6. Define make_request(url): a. If access_token is null or is_token_expired() returns true:
   • Call get_new_token() b. Add Authorization: Bearer {access_token} to request headers c. Send the request to url d. Return the response
7. Usage:
   • Call make_request("https://api.agentsync.io/v1/example")

Token Reuse Example (Python)

import requests
import datetime

client_id = "your_client_id"
client_secret = "your_client_secret"
token_url = "https://auth.agentsync.io/oauth2/token"

access_token = None
expiry_time = None

def get_new_token():
    global access_token, expiry_time
    data = {
        "grant_type": "client_credentials",
        "client_id": client_id,
        "client_secret": client_secret
    }
    response = requests.post(token_url, data=data).json()
    access_token = response['access_token']
    expires_in = response['expires_in']
    expiry_time = datetime.datetime.now() + datetime.timedelta(seconds=expires_in)

def is_token_expired():
    return datetime.datetime.now() >= expiry_time

def make_request(url):
    global access_token
    if access_token is None or is_token_expired():
        get_new_token()
    headers = {"Authorization": f"Bearer {access_token}"}
    return requests.get(url, headers=headers).json()

# Example usage
response = make_request("https://api.agentsync.io/v1/entities")