API Reference

Mosaic API - Authentication

Mosaic API

The Mosaic API is designed for robust and flexible integration capabilities. It supports simultaneous multi-instance integration and is platform-independent, ensuring compatibility with any API-enabled platform.

Getting Started

  1. Requesting an API Key

To start, reach out to your Mosaic Customer Success Manager to request an API Key. You'll need to provide:

  • The domain from which your server makes API calls.
    • Mosaic supports domains hosted on various platforms. Ensure that your domain is publicly accessible.
  • Your preference regarding callback enablement:
    • For an Auto-Generated Webhook URL in the format <domain>/webhook, ensure your server is set to accept callbacks via this Webhook URL.
    • If you prefer a Custom Webhook URL that does not adhere to the <domain>/webhook format, inform your Mosaic Customer Success Manager to accommodate this customization.
    • Mosaic advises using HTTPS for secure data transmission. If you need to use HTTP, indicate this preference in your Webhook URL setup.

Note: Ensure that all provided URLs are publicly accessible and properly configured to handle requests from Mosaic's servers. This includes setting up any necessary API Gateways or DNS records.

  1. Receiving Your API Key and Mosaic Team ID

Upon request, your Customer Success Manager will provide you with an API Key and your unique Mosaic Team ID.

Using Your API Key

To authenticate your API requests, you must include both your team_id and your API Key in the request headers.

Endpoint Structure

Use the following URL structure for your API requests:

  • Base URL (multi-tenant only): https://api-server.us-east-1.prod.mosaicapp.com
  • Base URL (single tenant only): https://api.[Tenant Name].prod.us-east-1.mosaicapp.com
  • Path: /api/{team_id}/{data_type}

In the request header, include your API Key and Origin (the domain used for making API calls):

  • {team_id}: Your unique team identifier.
  • {data_type}: The type of data you are accessing or manipulating.

API Access for Single Tenant Customers

Single tenant customers will receive a unique API server URL, distinct from the common URL in our standard documentation. Please use the provided URL for your environment to ensure seamless integration and complete access to our tailored API services.

Request Headers

When making API calls, include the following headers in your request:

  • Authorization: Your API Key
  • Origin: The domain used for making API calls
  • x-tenant: Your Tenant ID
  • x-realm-id: Your Realm ID

Example Header Configuration

Authorization: {api_key}
Origin: {domain}
x-tenant: {tenant_id}
x-realm-id: {realm_id}

Note

For teams without a dedicated tenant and realm, use "prod" for both x-tenant and x-realm-id.

Important Note

Your Origin header should match the domain or the base of your Webhook URL. If you are using an auto-generated webhook, exclude the final /webhook from the origin.

Example:

  • Webhook URL: https://myCoolApp.com/api/webhook
  • Origin: https://myCoolApp.com/

Ensure that the Origin accurately reflects the base domain to avoid integration issues.

API Rate Limit

The Mosaic API has a rate limit in place to ensure fair usage and maintain optimal performance for all users. The rate limit for Mosaic is set at 300 requests per 5 minutes, which averages to 1 request per second.

This means that you can make up to 300 requests to the Mosaic API within a 5-minute window. If you exceed this limit, you may receive a rate limit error response. It's important to manage your requests and ensure they stay within the specified limits to avoid disruptions in service.

Please note that the rate limit is subject to change based on system conditions and usage patterns. We recommend periodically checking our documentation for any updates or announcements regarding rate limit adjustments.

Security

The Mosaic API uses a secure authentication mechanism to ensure data privacy and access control:

  1. Authentication: All requests require a valid API token, obtained through our authentication endpoint. Tokens are user-specific and must be included in the header for each request as Authorization: Bearer <token>.

  2. Rate Limiting: API requests are subject to rate limits to maintain performance and security.

  3. Data Encryption: All data transmitted between clients and our API endpoints is encrypted via HTTPS to prevent unauthorized access.

  4. Access Control: User roles and permissions restrict access to sensitive data and endpoints, ensuring compliance with data governance standards.