Skip to main content

Creating Warrants

Now that you've set up object types and users, you can create warrants that define your specific access control rules.

A warrant is an access rule that defines the relationship between an object and a user or a userset. Each warrant can represent a relationship between a specific object and a specific user or, more broadly, a relationship between many objects of a particular object type and a particular user or set of users (a userset). Warrant uses the set of all warrants you create to resolve access checks made by your application at runtime.

You can create warrants via API. For example, we can create a warrant that specifies that user d6ed6474-784e-407e-a1ea-42a91d4c52b9 is an editor of store 7:

curl "https://api.warrant.dev/v1/warrants" \    -X POST \    -H "Authorization: ApiKey YOUR_KEY" \    --data-raw \    '{        "objectType": "store",        "objectId": "7",        "relation": "editor",        "user": {            "userId": "d6ed6474-784e-407e-a1ea-42a91d4c52b9"        }    }'

User Warrants#

A warrant specifying the relationship between a specific user and an object is a user warrant. User warrants are useful for implementing fine grained access control schemes where each user has a set of access rules dictating which objects they have access to. The warrant we created above specifying that user d6ed6474-784e-407e-a1ea-42a91d4c52b9 is an editor of store 7 is an example of a user warrant.

Userset Warrants#

A warrant specifying the relationship between a userset and an object is a userset warrant. Userset warrants are useful for implementing less granular access control schemes like Role Based Access Control (RBAC), where each user belongs to a group (or role) and is allowed to perform actions based on the group they belong to.

Creating Groups#

Let's create a new object type called group and use it along with our store object type to implement basic RBAC for our stores. Our group object type will look like this:

{    "type": "group",    "relations": {        "member": {}    }}

The object type above specifies that:

  • A group can have members
curl "https://api.warrant.dev/v1/object-types" \    -X POST \    -H "Authorization: ApiKey YOUR_KEY" \    --data-raw \    '{        "type": "group",        "relations": {            "member": {}        }    }'

With the group object type defined, we can now create warrants that specify which group(s) each user belongs to. For example, to add user d6ed6474-784e-407e-a1ea-42a91d4c52b9 to the group store_owner, we can create the following warrant:

{    "objectType": "group",    "objectId": "store_owner",    "relation": "member",    "user": {        "userId": "d6ed6474-784e-407e-a1ea-42a91d4c52b9"    }}
curl "https://api.warrant.dev/v1/warrants" \    -X POST \    -H "Authorization: ApiKey YOUR_KEY" \    --data-raw \    '{        "objectType": "group",        "objectId": "store_owner",        "relation": "member",        "user": {            "userId": "d6ed6474-784e-407e-a1ea-42a91d4c52b9"        }    }'

Creating Warrants on Groups#

Once we've defined group membership warrants, we can create userset warrants that reference a group instead of a user to specify that any member of the group has the specified relation with the object. For example, to specify that members of the store_owner group are editors of ANY store, we can create the following userset warrant:

{    "objectType": "store",    "objectId": "ANY",    "relation": "editor",    "user": {        "objectType": "group",        "objectId": "store_owner",        "relation": "member"    }}
curl "https://api.warrant.dev/v1/warrants" \    -X POST \    -H "Authorization: ApiKey YOUR_KEY" \    --data-raw \    '{        "objectType": "store",        "objectId": "ANY",        "relation": "editor",        "user": {            "objectType": "group",            "objectId": "store_owner",            "relation": "member"        }    }'

By using userset warrants, stores are no longer directly related to users and are instead related to groups. We could define another group called shopper and create warrants that give members of the shopper group the viewer relation on stores.