Skip to main content

GraphQL APIs

Schema Documentation​

You can view the Directory GraphQL API documentation in the GraphQL Playground. If you have an Aserto account, you can also access the Playground from within the Aserto Console

Authentication​

Two HTTP headers must be included in all requests to the directory API:

  • Authorization - an API key (basic <KEY>) or OAuth2.0 token (bearer <TOKEN>).

    API keys can be found under the Aserto Directory connection in the Connections page.

  • Aserto-Tenant-ID - the tenant ID of the organization being accessed.

    The ID of your account's default tenant can be found in the Aserto console by selecting "Account settings" in user drop-down menu at the top-right.

    You can find an organization's tenant ID in the console by selecting "Manage organization" in the in the organization drop-down menu.

Pagination​

Pagination is supported using the first and after arguments to queries and fields that represent collections.

The query below retrieves the display name of the first two objects in the directory.

Query
{
  objects(first: 2) {
    nodes {
      displayName
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
Result
{
  "data": {
    "objects": {
      "nodes": [
        {
          "displayName": "Karin Lamb"
        },
        {
          "displayName": "Nuno Farinha"
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "OC04NzQyLTQ5YWQtOTUyNi05NzA5YzAwYmIwZGUA"
      }
    }
  }
}

The results consist of two parts:

  • nodes is a list containing the returned objects.
  • pageInfo contains pagination metadata.
    • hasNextPage is false if the returned page is the last one, true otherwise.
    • endCursor contains a cursor that can be passed to the after parameter in order to retrieve the next page.

The following query requests the next object after the two retrieved by the query above:

Query
{
  objects(first: 1, after: "OC04NzQyLTQ5YWQtOTUyNi05NzA5YzAwYmIwZGUA") {
    nodes {
      displayName
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
Result
{
  "data": {
    "objects": {
      "nodes": [
        {
          "displayName": "Lukas Keller"
        },
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "OC02ZWNjLTQ1ZWQtYjI3OC1kODQ5YWI1ZjdjM2UA"
      }
    }
  }
}

Filters​

Unlike selectors that are used to pick individual objects, filters let you retrieve all items that match given criteria.

The following query asks for the first 10 group objects whose key contains the substring "management":

Query
{
  objects(
    first: 10
    where: {
      type: {name: {equals: "group"}}
      key: {contains: "management"}
  }) {
    pageInfo {
      hasNextPage
    }
    nodes {
      key
      displayName
      type {
        name
      }
    }
  }
}
Result
{
  "data": {
    "objects": {
      "pageInfo": {
        "hasNextPage": false
      }
      "nodes": [
        {
          "key": "sales-engagement-management",
          "displayName": "sales-engagement-management-group",
          "type": {
            "name": "group"
          }
        },
        {
          "key": "content-management-consulting",
          "displayName": "content-management-consulting-group",
          "type": {
            "name": "group"
          }
        },
        {
          "key": "project-management",
          "displayName": "project-management-group",
          "type": {
            "name": "group"
          }
        },
        {
          "key": "senior-management",
          "displayName": "senior-management-group",
          "type": {
            "name": "group"
          }
        }
      ]
    }
  }
}

Note: Filters have AND semantics. When multiple fields are given, such as key and type in the last example, the results only include objects that match all criteria.

Life Cycle Metadata​

Most types in the directory retain metadata about key events in their life cycle. Life cycle metadata is represented by the Lifecycle type, and can be retrieved from directory items with lifecycle property (e.g. Object.lifecycle).