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.

Scopes

Some AgentSync APIs require explicit OAuth 2.0 scopes. If your request fails with "access_denied" and "Policy evaluation failed", you need to include the required scope in your token request.

Scopes are granted per-API when your credentials are provisioned. Contact support@agentsync.io if you need a scope added to your credentials.

Contracting API Scopes

Pass required scopes in the scope parameter of your token request, space-separated. See Token Retrieval below for the complete request format.

Token Retrieval

Send a POST request to the token endpoint for your environment:

After obtaining your access token, all subsequent API requests must use the appropriate API base URLs for your environment — do not send API calls to the auth.* domain. See API Base URLs.

Required Parameters

Sample Token Request (cURL)

curl --request POST \
  --url https://auth.sandbox.agentsync.io/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=YOUR_CLIENT_ID \
  --data client_secret=YOUR_CLIENT_SECRET \
  --data 'scope=rino_api_agency_read rino_api_agency_write'

Omit the scope parameter if your API does not require it.

Sample Token Responses

200 Success

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "xyz123",
  "scope": "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 Limits to learn more.

Token Expiration & Reuse

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

Recommended Strategies

• Reuse tokens — don't request a new token per API call
• Preemptive refresh — refresh 5 minutes before expiry to avoid mid-request failures
• Handle 401s gracefully — catch 401 Unauthorized responses, re-authenticate, and retry once

Token Reuse Example (Python)

import time
import requests

class TokenClient:
    TOKEN_BUFFER_SECONDS = 300  # refresh 5 minutes before expiry

    def __init__(self, client_id, client_secret, token_url, scope=None):
        self.client_id = client_id
        self.client_secret = client_secret
        self.token_url = token_url
        self.scope = scope
        self._token = None
        self._token_expiry = 0.0

    def get_token(self):
        """Return a valid token, refreshing if expired or not yet set."""
        if not self._token or time.time() >= self._token_expiry:
            self._refresh()
        return self._token

    def _refresh(self):
        data = {
            "grant_type": "client_credentials",
            "client_id": self.client_id,
            "client_secret": self.client_secret,
        }
        if self.scope:
            data["scope"] = self.scope
        response = requests.post(self.token_url, data=data)
        response.raise_for_status()
        token_data = response.json()
        self._token = token_data["access_token"]
        self._token_expiry = time.time() + token_data["expires_in"] - self.TOKEN_BUFFER_SECONDS


# Usage — scope is optional, include only if required by the API
client = TokenClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    token_url="https://auth.sandbox.agentsync.io/oauth2/token",
    scope="rino_api_agency_read rino_api_agency_write",
)

headers = {"Authorization": f"Bearer {client.get_token()}"}