Introduction

Mosaic builds every feature using an API-first approach, to give you APIs that are consistent, reusable, and well-designed. This lets you create great identity experiences for your users, and develop better products—faster.

Base URL

Mosaic APIs are served over HTTPS. The endpoint paths are relative to the base URL, which is comprised of:

  • Scheme, which defines the protocol used. Always https .
  • Host, which varies depending on the tenant's region. Hosts are production environments.
    • api.transmitsecurity.io (global, US)
    • api.eu.transmitsecurity.io (EU)
    • api.ca.transmitsecurity.io (Canada)
    • api.au.transmitsecurity.io (Australia)
  • ServiceID, which identifies the type of service, for example:
    • cis — Identity Management and Authentication services
    • risk — Detection and Response services
    • verify — Identity Verification services

For example:

  • https: // api.transmitsecurity.io / risk /v1/recommendation
  • \_scheme_/\__________host___________/\_serviceID_/\__endpoint_path__/
Note

Examples in Mosaic documentation always leverage the global host (api.transmitsecurity.io). Make sure to check the correct base URL for your region and adjust code snippets as needed.

Authentication

All API requests must be made over HTTPS. Depending on the API and client settings, authentication is performed either using:

  • Client ID only
  • Client ID with PKCE
  • PKCE only
  • Client ID and Client Secret
  • OAuth2 Access Token in the Authorization header using Bearer authentication scheme

Access tokens

These are the types of access tokens that can be used to authorize API calls in Mosaic.

  • Client access tokens — generated using your app credentials
  • Admin access tokens — generated using credentials of management apps
  • User access tokens — returned upon successful user authentication

For more information about token types, see Token reference.

Important

In some cases, client access tokens must be generated for the specific service you want to use. For Detection and Response, and Identity Verification services, specify the relevant resource when generating the token. See Authorization.

To generate access tokens to run API calls right from the docs, using the Try it button.

Access to APIs

Mosaic restricts access to some APIs authorized by client access tokens by enforcing client role-based access. To be able to run calls to a specific endpoint, a client must be assigned a role that grants appropriate permissions. For details, see Manage client roles. APIs currently protected with RBAC:

APIs authorized using user access tokens or admin access token don't impose any role requirements.

Errors

Conventional HTTP response codes are used to indicate the success or failure of an API call:

  • 2xx or 3xx codes indicate success
  • 5xx codes indicate a Mosaic Server server error (rare)
  • 4xx codes indicate other failures (missing params, unauthorized, applicative errors, etc.)