Skip to main content

Concepts

Tenants​

The warrify platform is multi-tenant. Every resource is associated with a tenant. Typically a tenant is:

  • a retail chain
  • a PoS provider that develops the warrify integration
  • a warrify partner that offers a warrify integration to their customers

But an organization can have multiple tenants, for example:

  • A retail conglomerate with multiple subsidiaries can have a tenant for each subsidiary.
  • A retail chain with different independent brands can have a tenant for each brand. (this however is not recommended, as it is not possible to share resources between tenants. If only branding is required, it is recommended to use the $.attributes.retailer.brand field instead)
  • A single organization can have multiple tenants for different purposes, for example a tenant for production and a tenant for testing.

When using the warrify platform, you will need to specify the tenant for each request. This is typically done by specifying the tenant in the path of the request URL.

info

Tenants are a logical separation of resources. A single user can have access to multiple tenants. Similarly, a single set of API credentials can be used to access multiple tenants. To learn more about users and API credentials, see the Permissions section.

Permissions​

Every API call on the warrify platform requires authorization. Whether a caller is authorized to perform an action is determined by the combination of:

  1. the principal (i.e. the user_id of the user or the client_id of the API credentials)
  2. the action (e.g. checkout:sales:create)
  3. the resource (e.g. urn:warrify-com:3a3567e0-acb3-4db3-89d6-e542fb9516ac:eu-1:checkout:sales:*)

The fact that permissions are completely decoupled from the resource hierarchy (i.e. tenant) and the principal allows for a very flexible permission model. For example to use a third party offering that utilizes the warrify platform a retailer does not need to create a new set of API credentials for the third party but can instead grant the third party access to the retailer's existing API credentials via permissions.

tip

When looking at an API call in our documentation, you will see the required permissions for that API call in the AUTHORIZATIONS section (listed as a scope). Actions follow the format {service}:{resource}:{operation}, where {service} is the name of the service (e.g. checkout), {resource} is the resource type in plural form (e.g. sales) and {operation} is the operation to be performed (e.g. create).

Extensions​

Extensions are a way to adapt the API to local laws and regulations as well as to support custom use cases. They include return processing, warranty information, and more. Extensions are defined by the $.attributes.extensions field.

Attachments​

Arbitrary files can be attached to resources via the $.attributes.attachments field. Attachments are stored in a separate storage system and are not part of the resource itself. While attachments can be updated separately from the resource, every sale references a specific version of an attachment and thus the update of an attachment will not affect existing sales.