Skip to main content

​
OpenAPI Specification

Download our OpenAPI specification to import into Postman or other API tools:

Download OpenAPI JSON

Download the complete OpenAPI 3.0 specification file

​
Authentication

API endpoints are authenticated using JWT tokens. Include your signed JWT token in the Authorization header of your requests: 
{
  "Authorization": "Bearer <your_signed_jwt_token>"
}
To obtain a JWT secret, please reach out to the Reach team at [email protected]

​
API Route Patterns

Our API uses two route patterns with different authentication requirements:

​
Partner Routes (/partner/*)

APIs which begin with /partner use partner-scoped JWT tokens and are used for actions which apply to the partner as a whole. These routes manage partner-level resources and configurations.

​
Tenant Routes (/api/*)

APIs which begin with /api/ are tenant-scoped. They can use either:
  • A tenant-scoped JWT token (the tenant is identified from the tenantExternalId field in the JWT, so no header is needed), OR
  • A partner-scoped JWT token with the reach-tenant-id header set (required), which allows you to take action on the specific tenant
When using a partner-scoped JWT with tenant routes, you must include the tenant ID header: 
{
  "Authorization": "Bearer <your_partner_scoped_jwt_token>",
  "reach-tenant-id": "<tenant_id>"
}

​
JWT Token Types

We have two types of JWT tokens:

​
Tenant Scoped JWT

This is a JWT token that contains the tenant’s external ID (tenantExternalId) and is signed with your partner secret. This can be used to send to your Frontend client in order to allow them to make requests that only have access to that tenant.

​
Partner Scoped JWT

This is a JWT token that contains your partner ID and is signed with your partner secret. This can be used to make requests to partner-level API endpoints or tenant-level endpoints when combined with the reach-tenant-id header. Learn more about our JWT tokens