Skip to content

GraphQL Channel

  • Choose fields

    Ask for attributes from your configured entry types.

  • Read results

    Use the returned data and cursor for further pages.

A GraphQL query selects the entry fields your app needs.

You can send a query and inspect the schema for your configured directory.

Next: API access

Ask for exactly the fields you need. The GraphQL channel generates its schema from your entry type configuration, so the API always matches your directory.

Enable the channel:

Terminal window
SCRIBE_GRAPHQL_ENABLED=true
URLWhat you get
/graphqlQuery endpoint (POST) and GraphiQL IDE (GET)
/graphql.sdlSchema in SDL format
/graphql.jsonSchema as JSON introspection

Open /graphql in a browser to explore the schema interactively — the GraphiQL UI includes a schema browser, autocompletion, and query history.

Entry typeuserGraphQL schemaUser · user · usersQueryusers{nodes{cn mail}}Responsecn, mail onlygeneratesoffers fieldsreturns selected
Entry typeuserGraphQL schemaUser · user · usersQueryusers{nodes{cn mail}}Responsecn, mail onlygeneratesoffers fieldsreturns selected
Configured entry types become schema fields, and a query receives only the attributes it selects.

Hyphens and underscores are normalized, so organizational-unit, organizational_unit, and OrganizationalUnit all produce the same schema:

Config nameGraphQL typeLookup fieldCollection field
organizational-unitOrganizationalUnitorganizationalUnit(id: ...)organizationalUnits(...)
user or usersUseruser(id: ...)users(...)

Duplicate type names that produce the same GraphQL symbol in any category (type name, lookup field, or collection field) cause startup failure. Examples: foo-bar and foo_bar collide on all three; user and users collide because both normalize to the same lookup and collection names. Names starting with digits or other invalid GraphQL characters are normalized with an underscore prefix.

Attribute names are exposed as GraphQL field names. Names that are already valid GraphQL fields stay unchanged; hyphenated names are converted to lower camel case. For example, mail-Primary appears as mailPrimary in the schema and in queries.

If a hyphenated name contains mixed case, each part is lowercased before the name is joined, so DirXML-EntitlementRef appears as dirxmlEntitlementref. If two attributes in the same type normalize to the same GraphQL field name (e.g. a-b and aB both map to aB), startup fails with a collision error before the schema is served. Use distinct catalog attribute names so each normalizes to a unique field.

Use the GraphiQL schema explorer or fetch /graphql.sdl for exact names.

query {
users(filter: "department=Engineering", first: 25, sort: "-modifyTimestamp") {
nodes {
entryDN
cn
mail
}
pageInfo {
hasNextPage
endCursor
}
}
}

Look up by any identifier format:

query {
user(id: "dXNlcjo5aXg") {
entryDN
cn
mail
memberOf
}
}

When you don’t know the entry type, use node:

query {
node(id: "dXNlcjo5aXg") {
... on User { cn, mail }
... on Group { cn, member }
}
}

Filter syntax matches the REST API — use FleX, JSON, SCIM, or LDAP format:

users(filter: "department=Engineering AND active=true")

Relay-style cursor pagination. Use first/after to page forward:

First requestusers(first: 25)Page 1pageInfo.endCursorNext requestafter: endCursorPage 2hasNextPagereturnsendCursor → afterreturns
First requestusers(first: 25)Page 1pageInfo.endCursorNext requestafter: endCursorPage 2hasNextPagereturnsendCursor → afterreturns
pageInfo.endCursor from one collection response becomes after in the next request.
query {
users(first: 25, after: "Y3Vyc29yOjI1") {
nodes { cn }
pageInfo { hasNextPage endCursor }
}
}

Use count(mode: ESTIMATED) for fast approximate counts, or count(mode: EXACT) when you need precision. If mode is omitted, GraphQL uses channels.graphql.default-count. Exact counts are still bounded by the query time limit; very large result sets can return a timeout error instead of a count.

When a collection query omits sort, GraphQL uses channels.graphql.default-sort, which inherits query.default-sort. The default is null, so result order stays database-native unless you configure a default or the client sends sort.

View an entry’s state at any moment. The at argument accepts timestamps, durations, cursors, and relative expressions like now-1h. See Temporal references for all accepted formats.

{ user(id: "dXNlcjo5aXg", at: "2024-01-15T10:00:00Z") {
cn mail department
} }

Query changes across all entry types or per-entry:

query {
changes(range: "24h", type: [MODIFY], first: 100) {
nodes {
id
type
timestamp
entryType
data {
... on ModifyData {
diff { attribute operation value }
}
}
}
pageInfo { hasNextPage endCursor }
}
}

Filter by time range (range, since/until), event type (ADD, MODIFY, MOVE, DELETE), entry type, or affected attributes. Sort by timestamp or -timestamp.

Rank entries by how many changes they received in a time window:

query {
hotChanges(range: "24h", first: 20, sort: "-samples") {
nodes {
samples
firstTimestamp
lastTimestamp
entryType
entryID
entryName
}
pageInfo { hasNextPage endCursor }
}
}

Each entry also has a changes field for its own history:

user(id: "dXNlcjo5aXg") { changes(first: 5) { nodes { type timestamp } } }

Change events support three data formats: diff, patch, and merge.

Hash-only requestsha256HashQuery-text cachehash → textExecutefresh resultsNot foundPERSISTED_QUERY_NOT_FOUNDQuery + hashfull textlooks upquery textnot cachedresendsstores text
Hash-only requestsha256HashQuery-text cachehash → textExecutefresh resultsNot foundPERSISTED_QUERY_NOT_FOUNDQuery + hashfull textlooks upquery textnot cachedresendsstores text
APQ reuses query text by its hash; a cache miss asks the client to send that text again.

APQ caches query text, not results, keyed by its SHA-256 hash: clients send the 64-character hexadecimal hash instead of the full query. On the first request the client sends both the query and its hash; after that, the hash is enough.

Hash-only requests also work over GET, with the hash in the extensions parameter. Every response is sent with Cache-Control: no-store, so browsers and CDNs do not cache results. Apollo Client, urql, and other GraphQL clients handle the APQ flow automatically. See Configuration Reference for cache size and TTL settings.

Three layers protect against abusive queries:

LayerProtection
Parser limitsReject oversized payloads before parsing
Depth limitsReject deeply nested queries
Complexity limitsReject queries selecting too many fields

Defaults work for most deployments. See Configuration Reference for tuning.

Timestamp fields (createTimestamp, modifyTimestamp, verifiedTimestamp) accept a format argument with presets like ISO, UNIX, UNIX_MS, RFC_1123, LDAP, or custom DateTimeFormatter patterns:

user(id: "...") { modifyTimestamp(format: "UNIX_MS") }

See Signals for metrics, Error Handling for error codes.