Query

Query for a set of warrants using a query syntax.

GET /v1/query?q=QUERY

Parameters

Parameter	Description	Type	Required
query	Query to find all warrants for a given object or subject.	Query param	yes

Query Clauses

Clause	Description
select	Specifies the type of results to be returned by the query. Optionally, the explicit keyword can be provided (i.e. explicit warrants) to specify that only explicit results be returned. By default, both implicit and explicit results are returned.
for	A condition specifying what object or subject, with optional context, to query results for (i.e. "get all warrants for role:admin"). Only those warrants matching all of the conditions in the for clause are selected. If the explicit keyword is not specified in the select param, the resulting warrants are then expanded to determine if they imply other warrants (i.e. "the owner of a report is also an editor of that report"). For object and subject filters, you can filter on all object ids by using the * character (i.e. role:*).
where	A list of conditions to be applied to the result set before it is returned. If a where clause is provided, the query will only return results matching all conditions. For object and subject filters, you can filter on all object ids by using the * character, i.e. role:*.
group	Specifies whether to group the results by the resulting warrants' object or subject. Accepted values are object or subject.

Syntax

[SELECT | SELECT EXPLICIT] [warrant|permission|role|pricing-tier|feature|user|tenant|#{objectType}]*
FOR
    [object = {objectType}:[objectId|*] | subject = {objectType}:[objectId|*](#{relation})]
    [AND context={context}]
WHERE
    object = {objectType}:[objectId|*] AND
    relation = {relation} AND
    subject = {objectType}:[objectId|*]#{relation} AND
    context = {context}
[GROUP] [object|subject]

Example Queries

Get all permissions for user 1

SELECT warrant, permission
FOR subject=user:1
WHERE object=permission:* AND subject=user:1

Get all explicit permissions for user 1

SELECT EXPLICIT warrant, permission
FOR subject=user:1
WHERE object=permission:* AND subject=user:1

Get all roles for user 1

SELECT warrant,role
FOR subject=user:1
WHERE object=role:* AND subject=user:1

Get all explicit roles for user 1

SELECT EXPLICIT warrant,role
FOR subject=user:1
WHERE object=role:* AND subject=user:1

Get all features for user 1

SELECT warrant,feature
FOR subject=user:1
WHERE object=feature:* AND subject=user:1

Get all pricing tiers for user 1

SELECT warrant,pricing-tier
FOR subject=user:1
WHERE object=pricing-tier:* AND subject=user:1

Get all tenants that have access to feature 1

SELECT warrant,tenant
FOR object=feature:1
WHERE subject=tenant:*

Get all tenants that are part of the pro pricing-tier

SELECT warrant
FOR object=pricing-tier:pro
WHERE object=pricing-tier:pro AND subject=tenant:*

Get permissions for all users in tenant 1

SELECT warrant,permission,tenant
FOR subject=user:*(HAVING relation=member WITH object=tenant:1)
WHERE object=permission:* AND relation=member AND subject=user:*
GROUP subject

Examples

Query for all explicit warrants that user 1 where user 1 has a member relation

curl "https://api.warrant.dev/v1/query?select=explicit&20warrants&for=subject=user:1&where=relation=member%2Csubject=user:1" \
    -H "Authorization: ApiKey YOUR_KEY"

Query for all roles that user 1 has a relation to

curl "https://api.warrant.dev/v1/query?select=warrants&for=subject=user:1&where=object=role:*%2Csubject=user:1" \
    -H "Authorization: ApiKey YOUR_KEY"

Query for all warrants that exist for the admin role

curl "https://api.warrant.dev/v1/query?select=warrants&for=object=admin:role" \
    -H "Authorization: ApiKey YOUR_KEY"

Query for all explicit warrants that exist for tenant 7

curl "https://api.warrant.dev/v1/query?select=explicit%20warrants&for=subject=tenant:7" \
    -H "Authorization: ApiKey YOUR_KEY"

Request

Curl

curl "https://api.warrant.dev/v1/query?q=SELECT%20warrant%20FOR%20object=pricing-tier:*%20WHERE%20subject=user:12" \
    -H "Authorization: ApiKey YOUR_KEY"

Go

queryResult, err := warrant.Query("SELECT warrant FOR object=pricing-tier:* WHERE subject=user:12", &warrant.ListWarrantParams{})
if err != nil {
    // handle error
}

Java

try {
    int limit = 100;
    int page = 1;
    Query q = Query.selectWarrants()
        .forClause("object=pricing-tier:*")
        .where("subject=user:12");
    Warrant[] warrants = client.queryWarrants(q, limit, page);
} catch (WarrantException e) {
    // Handle error
}

Python

warrants = warrant.Warrant.query(select="warrants", for_clause="object=pricing-tier:*", where="subject=user:12")

Ruby

Warrant::Warrant.query(select: "warrants", for: "object=pricing-tier:*", where: "subject=user:12")

Response

{
    "result": [
        {
            "objectType": "pricing-tier",
            "objectId": "enterprise",
            "relation": "member",
            "subject": {
                "objectType": "user",
                "objectId": "test-user1"
            },
            "directMatch": true
        },
        {
            "objectType": "pricing-tier",
            "objectId": "basic",
            "relation": "member",
            "subject": {
                "objectType": "user",
                "objectId": "test-user1"
            },
            "directMatch": false
        },
        {
            "objectType": "feature",
            "objectId": "analytics",
            "relation": "member",
            "subject": {
                "objectType": "user",
                "objectId": "test-user1"
            },
            "directMatch": false
        }
    ],
    "meta": {}
}