Skip to main content

API Integration

Overview​

This document provides guidelines for integrating with our API. The OpenAPI specification for the API can be found at ApiDocs. This specification includes detailed information about the available endpoints, request and response formats, and other essential details for successful integration.

Prerequisites​

  • Access to the API documentation at here.
  • API key or authentication credentials.
  • Familiarity with RESTful API concepts.

Getting Started​

1. Accessing the API Documentation​

The OpenAPI specification for our API can be downloaded using Download button when you visit page. This documentation provides comprehensive details about each endpoint, including:

  • Endpoint URLs: The URLs for accessing different API resources.
  • HTTP Methods: The HTTP methods (GET, POST, PUT, PATCH, DELETE) supported by each endpoint.
  • Request Parameters: The required and optional parameters for each request.
  • Response Formats: The structure of the responses returned by the API.
  • Error Codes: The possible error codes and their meanings.

2. Authentication​

To access the API, you need to authenticate using an API key or other authentication credentials. Include your API key in the request headers.

3. Obtaining Azure Client ID and Secret​

To integrate with our API, you need to obtain your Azure Client ID and Secret. Follow these steps:

  1. Log in to the Azure Portal: Go to Azure Portal and log in with your credentials.
  2. Navigate to Azure Active Directory: In the left-hand navigation pane, select "Azure Active Directory."
  3. App Registrations: Click on "App registrations" and then select your application. If you don't have an application registered, create a new one.
  4. Client ID: In the application overview, you will find the "Application (client) ID". Note this down.
  5. Client Secret: Go to "Certificates & secrets" in the left-hand menu. Under "Client secrets", click on "New client secret". Provide a description and expiration period, then click "Add". Copy the value of the client secret immediately as it will not be shown again.

4. Obtaining a Bearer Token​

To authenticate API requests, you need to obtain a Bearer token using your Azure Client ID and Secret. Follow these steps:

  1. Token Endpoint: Use the following endpoint to obtain the token:
  2. Request Parameters: Include the following parameters in your request:
  • grant_type: client_credentials
  • client_id: Your Azure Client ID
  • client_secret: Your Azure Client Secret
  • scope: api://mac.dev/.default
    • Note: For Prod scope: api://mac-prod/.default
  1. Example Request:
curl -X POST https://login.microsoftonline.com/05d75c05-fa1a-42e7-9cf1-eb416c396f2d/oauth2/v2.0/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=api://mac.dev/.default"