Introduction

Environments

To consume all the services of the Management API, you must point them to your production environment.

The production environment is the scenario that will support organizations that are already running in live environments. This environment will be available to the organization as long as it is active on the platform.

The URL to consume the APIs in the production environment is:

Getting access credentials

All Managements endpoints exposed by the API require authentication using an Access token, so when consuming the endpoints described in this document, you will need to have that token.

How can I get an access token?

To get an access token, follow these steps:

1. You must have a user belonging to your organization. This user must be of the Organization Owner or Organization Admin type.
2. Consume the platform authentication service (User login) using the access credentials associated with a user in the organization.
3. If the user belongs to more than one organization, choose the organization you want to manage with Select account. Every subsequent request is executed against the selected organization.

The access token has a limited lifetime. Read the exp claim of the token (Unix time, in seconds) to know when it expires, and request a new one with User login before that moment.

Additional note: To create users in the organization you must do so through the administration console, which can be accessed through the following URL:

For Production environment: https://suite.invoxmedical.com

Common responses

The following responses can be returned by every endpoint that requires an access token. They are not repeated in detail on each page.

Unauthorized — 401

The access token is missing, malformed or expired.

{
  "message": "Unauthorized"
}

Forbidden — 403

The access token is valid, but the user does not have the Organization Owner or Organization Admin role in the selected organization.

{
  "message": "Access denied: you do not have the required permissions."
}

Error format — 4xx

Unless a page states otherwise, platform errors share this structure:

type ManagementErrorResponse = {
  errorType: string;     // Machine-readable error code. Use it in your integration logic
  errorMessage: string;  // Human-readable description of the error
  message?: string;      // Same value as errorMessage. Present on validation errors
  details?: object[];    // Validation detail. Present on validation errors
};

Most validation errors (missing or malformed fields) return errorType: "invalidRequestFormat", and errorMessage identifies the first field that failed. Each page lists the exact errorType and errorMessage values it returns.

Server error — 5xx

An unexpected error occurred while processing the request. The body contains a message field, or an errorMessage field in Delete user. You can retry the request later.