Create a Warrant

Create a new warrant that associates a subject (e.g. user:john-doe) to an object (e.g. report:balance-sheet) via a relation (e.g. editor).

Endpoint

POST /v2/warrants

Request

Body

---

objectType string

The type of object. Must be one of your system's existing object types.

---

objectId string

The id of the specific object.

---

relation string

The relation for this object to subject association. The relation must be valid as per the object type definition.

---

subject object

The subject for which this warrant applies. Subject can be a specific object (by id) or a set of objects matching the given objectType, objectId and relation.

---

policy string, optional

A boolean expression that must evaluate to true for this warrant to apply. The expression can reference variables that are provided in the context attribute of access check requests. See Key Concepts > Warrants > Policies & Context to learn more about writing policies.

---

cURL

POST /v2/warrants

curl "https://api.warrant.dev/v2/warrants" \
    -X POST \
    -H "Authorization: ApiKey YOUR_KEY" \
    --data-raw \
    '{
        "objectType": "report",
        "objectId": "23ft346",
        "relation": "editor",
        "subject": {
            "objectType": "user",
            "objectId": "15ads7823a9df7as433gk23dd"
        }
    }'

CLI

POST /v2/warrants

warrant assign user:15ads7823a9df7as433gk23dd editor report:23ft346

Go

POST /v2/warrants

createdWarrant, err := warrant.Create(&warrant.WarrantParams{
    ObjectType: "report",
    ObjectId:   "23ft346",
    Relation:   "editor",
    Subject: warrant.Subject{
        ObjectType: "role",
        ObjectId: "15ads7823a9df7as433gk23dd",
    },
})
if err != nil {
    // handle error
}

Java

POST /v2/warrants

try {
    Report report = new Report("23ft346"); // assuming 'Report' implements the 'WarrantObject' interface
    client.createWarrant(report, "editor", new WarrantSubject("user", "15ads7823a9df7as433gk23dd"));
} catch (WarrantException e) {
    // Handle error
}

Node.js

POST /v2/warrants

const newWarrant = await warrantClient.Warrant.create({
    object: {
        objectType: "report",
        objectId: "23ft346",
    },
    relation: "editor",
    subject: {
        objectType: "user",
        objectId: "15ads7823a9df7as433gk23dd",
    },
});

PHP

POST /v2/warrants

$subject = new \Warrant\Subject("user", "15ads7823a9df7as433gk23dd");
$created_warrant = $warrant->createWarrant(new \Warrant\Warrant("report", "23ft346", "editor", $subject));

Python

POST /v2/warrants

user_subject = warrant.Subject("user", "15ads7823a9df7as433gk23dd")
warrant.Warrant.create(object_type="report", object_id="23ft346", relation="editor", subject=user_subject)

Ruby

POST /v2/warrants

created_warrant = Warrant::Warrant.create(
    {
        object_type: "report",
        object_id: "23ft346",
    },
    "editor",
    {
        object_type: "user",
        object_id: "15ads7823a9df7as433gk23dd"
    }
)

Response

Headers

---

Warrant-Token string

A unique transaction identifier for this write operation. Can be cached and passed on subsequent read requests.

---

Body

---

objectType string

The type of object. Must be one of your system's existing object types.

---

objectId string

The id of the specific object.

---

relation string

The relation for this object to subject association. The relation must be valid as per the object type definition.

---

subject object

The subject for which this warrant applies. Subject can be a specific object (by id) or a set of objects matching the given objectType, objectId and relation.

---

policy string

A boolean expression that must evaluate to true for this warrant to apply. The expression can reference variables that are provided in the context attribute of access check requests. See Key Concepts > Warrants > Policies & Context to learn more about writing policies.

---

200 OK

{
  "objectType": "report",
  "objectId": "23ft346",
  "relation": "editor",
  "subject": {
    "objectType": "user",
    "objectId": "15ads7823a9df7as433gk23dd"
  }
}