M2M Authentication

Overview

This API uses Machine-to-Machine (M2M) authentication based on OAuth 2.0 with client_credentials grant type. You exchange your credentials for an access token, then use that token to call the API.

Prerequisites

client_id and client_secret provided by AVIV Group
Audience: https://api.aviv-group.com/caas/v3
Sandbox audience: https://api.aviv-group.com/sandbox/caas/v3
An intermediary_id identifying the agency on behalf of which you are making requests

Authentication Endpoint

POST https://auth.api.aviv-group.com/oauth/token
Content-Type: application/json

Request

Send a POST request with the following JSON body:

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "client_credentials",
  "audience": "https://api.aviv-group.com/caas/v3",
  "intermediary_id": "your_intermediary_id"
}

Parameter	Required	Description
`client_id`	Yes	Your application's client identifier
`client_secret`	Yes	Your application's client secret
`grant_type`	Yes	Must be `client_credentials`
`audience`	Yes	`https://api.aviv-group.com/caas/v3`
`intermediary_id`	Yes	Identifier of the intermediary agency in your system

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Using the Token

Include the access token in the Authorization header of every API request:

GET /caas/v3/your-endpoint HTTP/1.1
Host: api.aviv-group.com
Authorization: Bearer <access_token>
User-Agent: YourApp/1.0

Important: Always include a valid User-Agent header — requests without it will be blocked by the firewall.

⚠️ Token Reuse Policy: Access tokens are valid for 24 hours. Your implementation must cache and reuse the token for the entirety of its lifetime — do not request a new token per call. Token reuse is verified during the sandbox review and is a prerequisite for production access.

Sandbox

A sandbox environment is available for testing. Use a different audience:

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "client_credentials",
  "audience": "https://api.aviv-group.com/sandbox/caas/v3",
  "intermediary_id": "your_intermediary_id"
}

Sandbox base URL: https://api.aviv-group.com/sandbox/caas/v3

Code Examples

PHP

<?php
$tokenUrl = 'https://auth.api.aviv-group.com/oauth/token';

$payload = [
    'grant_type'    => 'client_credentials',
    'client_id'     => 'your_client_id',
    'client_secret' => 'your_client_secret',
    'audience'      => 'https://api.aviv-group.com/caas/v3',
    'intermediary_id' => 'your_intermediary_id',
];

$ch = curl_init($tokenUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

// Use $response['access_token'] in subsequent API calls

Python

import requests

token_url = "https://auth.api.aviv-group.com/oauth/token"

payload = {
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "audience": "https://api.aviv-group.com/caas/v3",
    "intermediary_id": "your_intermediary_id",
}

response = requests.post(token_url, json=payload)
access_token = response.json()["access_token"]

# Use the token in subsequent API calls
headers = {
    "Authorization": f"Bearer {access_token}",
    "User-Agent": "YourApp/1.0",
}