Skip to main content

Objects

Every warrant represents a relationship between two resources in an application. These resources are typically persisted in the application's datastore (e.g. MySQL, MongoDB, etc). In Warrant, they are referred to as objects.

Overview​

     report     :   balance-sheet
|-------------|   |---------------|
| Object Type |   |   Object ID   |
|-------------|   |---------------|

Objects consist of three attributes:

  • Object Type - Specifies what type of entity a particular resource is (e.g. a user, a tenant, a report, etc).
  • Object ID - Specifies a unique identifier for the resource (typically the resource's primary key in the datastore).
  • Meta (optional) - A JSON object containing additional data related to the object (e.g. a user's email address, a tenant's display name, a description of the privileges a role grants, etc).

Objects make it easier to manage the warrants associated with each resource (via API and/or Dashboard) and provide a way for applications to persist authorization-specific data outside of (or often, in lieu of) their primary datastore.

Creating and Managing Objects​

Warrant automatically creates objects for resources referenced in the object and subject clauses of warrants when they are created. This means developers using Warrant don't need to worry about manually creating objects.

For example, given the following warrant:

report:balance-sheet#editor@user:john-doe
{
  "objectType": "report",
  "objectId": "balance-sheet",
  "relation": "editor",
  "subject": {
    "objectType": "user",
    "objectId": "john-doe"
  }
}

Warrant will create the following two objects:

report:balance-sheet
{
  "objectType": "report",
  "objectId": "balance-sheet"
}
user:john-doe
{
  "objectType": "user",
  "objectId": "john-doe"
}

Objects can be managed from the Warrant Dashboard and/or via API. Refer to the Objects API Reference to learn more about managing objects via API.

note

When an object is deleted, any warrants associated with the object will automatically be deleted. This makes it easier for applications to remove any warrants associated with an object when the object is deleted from the application itself.

Metadata​

Objects can be augmented with additional authorization-specific metadata (e.g. the display name for a role or permission, the description of a particular feature, etc). Metadata is especially useful when implementing permission-specific user interfaces. For example, when building a customer-facing page for managing team-level roles and permissions, metadata can provide user-friendly names and descriptions of what actions/resources each role or permission will grant to a user.

user:john-doe w/ metadata
{
  "objectType": "user",
  "objectId": "john-doe",
  "meta": {
    "email": "john-doe@acme-corp.com",
    "isActivated": true
  }
}
role:accountant w/ metadata
{
  "objectType": "role",
  "objectId": "accountant",
  "meta": {
    "name": "Accountant",
    "description": "Allows a user to view the financial reporting pages and edit charges."
  }
}