Welcome to the MotionTools API documentation!

Please note that when using API Token authentication this header must not be set!

All clients must set the X-Client-Version header to their applicable Client ID and Version, like MyCustomerApp/1.0.0. The header is used for identifying the applicable tenant to enable multi-tenancy, as well as for enabling the expiration of outdated clients.

• If the client version is disallowed the backend will send a 410 Gone HTTP response code. Upon this response clients must show a notification to the user to upgrade their app.
• If the client version is unknown the backend will return a 400 HTTP response with the unknown_tenant error code.
• Some client versions are permitted only for a specific user role. This is currently only enforced on sign up and sign in routes, which will render the user unable to obtain an access/refresh token. If the client is being used by a user that doesn't have a supported role, a 403 HTTP response code will be returned with the error_code client_role_mismatch. It's up to the client to handle this specific status and error code combination gracefully.

X-Deprecated header is returned only on staging if a deprecated endpoint is called, or if a deprecated param is passed. When a deprecated endpoint is called, this header will have deprecated_action as value. If a deprecated param (or params) is passed, then the name of this param will be the value.

Errors are broadly indicated via HTTP status and further narrowed down using an error code in the response payload. Human-readable descriptions are implementor-facing and meant to help in understanding issues, not user-facing.

{
  "error_code": "hello_world",
  "description": "Some brief description"
}

Some errors like failed validations may contain additional data in the response in order to clarify to the user what was wrong more easily. These messages are localized based on the sent Accept-Language and should be displayed as applicable:

• If an error key matches a request parameter the messages can be displayed along that field
• If an unknown error key is encountered (this can happen for multi-parameter composite validations like "one of email or phone must be set") all those messages should be displayed in a central place on top or at the bottom of the UI

A validation error response looks like this:

{
  "errors": { first_name: ["is blank"] },
  "error_code": "validation_failed",
  "description": "The request parameters did not satisfy validation rules for this resource."
}

In case the request parameters input is an array, ie. {"invitations": [{ "role": null }]} the validation error response will be further grouped by the corresponding items index in the input array, for example:

{
  "errors": {
    0: { "role": ["is blank"] }
  }
}

See documentation for the user invitations endpoint for a more detailed example.

All clients must set the standard Accept-Language HTTP header explicitly and manually to the IETF language tag (en-US) or ISO639-1 (en) locale chosen by the client for client-side message localization.

The reason for this is aligning translated messages stored and shown on the client side with those from the backend, most notably on validation error messages. For example if a client supports only en and de but the device is actually set fr, if the client does not explicitly state which language it picked the backend might make a differing choice based on available backend languages or configured default fallback language.

Note that this does not affect "core" translations, which should not be fetched from the backend dynamically but be defined and used in the clients themselves.

Additionally the backend stores the user's current language to use for server-side issued user-facing communication like e-mails and push notifications.

From the total pool of supported languages, only a subset is enabled for any tenant, and one of these is the default locale.

Clients must use only available locales for the tenant, so if a tenant supports en and de and has a default of de, if fr is also a MotionTools supported language a client on a device configured to be fr locale must then fall back to the default locale de, because fr is not in the enabled list.

For mobile apps, the default and supported locales are baked in the apps at compile time currently. For web clients the frontend configuration endpoin