Channels

Access IdentityScribe through LDAP, REST, GraphQL, or MCP. All channels use the same query engine, so they behave consistently.

Channels are the front door to IdentityScribe:

• LDAP — Standard directory protocol for enterprise integrations
• REST — HTTP/JSON API for modern web applications
• GraphQL — Flexible query API for frontend-driven data fetching
• MCP — Model Context Protocol for AI coding assistants
• gRPC — High-performance binary protocol (roadmap)

All channels share the same directory pipeline (normalize → plan → compile → execute). Behavior and observability are identical across protocols.

LDAP bind authentication is available today. Unified JWT bearer token authentication is on the roadmap — when available, the same token will work across all channels.

Authorization is handled at the directory level, not per-channel. Permissions are evaluated during query execution based on the authenticated principal.

Channels support pagination appropriate to their protocol:

All channels share the unified failure model documented in Failures. Errors are mapped to protocol-appropriate responses:

See Failures for the complete error contract, retry guidance, and troubleshooting.

Every entry can be referenced using any of these formats:

All channels accept all formats. GlobalId is recommended for performance since the entry type is encoded in the ID.

Every entry response includes metadata:

Time-based parameters support flexible formats for expressing timestamps and durations. These work consistently across all channels.

Temporal lookup (at parameter): Point-in-time queries to view entry state at a specific moment.

# View entry state as it was 1 hour ago
curl "/api/users/123?at=now-1h"

# View entry state on a specific date
curl "/api/users/123?at=2024-01-15"

Changes API (range, since, until): Query entry change history within a time window.

# Changes in the last 24 hours
curl "/api/users/123/changes?since=now-1d"

# Changes between two dates
curl "/api/users/123/changes?since=2024-01-01&until=2024-02-01"

# Last 7 days of changes
curl "/api/users/123/changes?range=7d"

Filter expressions: Use temporal references in filter comparisons on timestamp attributes.

# Users modified in the last hour
curl "/api/users?filter=modifyTimestamp ge now-1h"

# Users created this week
curl "/api/users?filter=createTimestamp ge now-7d"

# Users not verified in over 30 days
curl "/api/users?filter=verifiedTimestamp lt now-30d"

All three timestamp attributes (createTimestamp, modifyTimestamp, verifiedTimestamp) support temporal references in filter expressions.

All channels emit metrics and traces through the unified observability stack:

Channel requests create root spans named {Channel}.{Operation} (e.g., LDAP.Search, REST.GET), with nested spans for each query pipeline stage.

The /observe/channels endpoint exposes enabled channels and their runtime binding information:

curl -s http://localhost:8080/observe/channels | jq '.channels'

Returns channel status, connection URLs, and actual bound ports (useful for ephemeral port 0). See Monitoring Guide for details.

The /.well-known/api-catalog endpoint provides machine-readable API discovery per RFC 9727. Clients can discover all available HTTP API channels and their schema URLs from a single endpoint:

curl -s http://localhost:8080/.well-known/api-catalog

Returns a Linkset document with service-desc (schema URLs) and service-doc (documentation/playground URLs) for each enabled channel:

{
  "linkset": [
    {
      "anchor": "/api",
      "service-desc": [
        {"href": "/api.json", "type": "application/json"},
        {"href": "/api.yaml", "type": "application/yaml"}
      ],
      "service-doc": [
        {"href": "/api", "type": "text/html"},
        {"href": "/docs/channels/rest", "type": "text/html"}
      ]
    },
    {
      "anchor": "/graphql",
      "service-desc": [
        {"href": "/graphql.json", "type": "application/json"},
        {"href": "/graphql.sdl", "type": "application/graphql"}
      ],
      "service-doc": [
        {"href": "/graphql", "type": "text/html"},
        {"href": "/docs/channels/graphql", "type": "text/html"}
      ]
    }
  ]
}

See RFC 9727 for the full specification.

See Observability for metrics, traces, and operational playbooks.

Channels are configured in the channels namespace. HTTP-based channels (REST, GraphQL) use the unified HTTP server with named sockets.

# HTTP server configuration (shared by REST, GraphQL, monitoring)
http {
  port = 8080
  host = auto  # localhost in dev, 0.0.0.0 in production
}

channels {
  # LDAP uses dedicated listeners
  ldap {
    listen = [
      { port = 10389 }
      { port = 10636, ssl { ... } }
    ]
  }

  # REST channel (serves at /api on the default HTTP socket)
  rest {
    enabled = true
    # socket = "@default"  # Optional: use named socket for separation
    ui.enabled = true
  }
}

See HTTP Server Configuration for socket binding, TLS, and named socket separation. See individual channel guides for detailed configuration options.

• LDAP Channel Guide — Configuration and usage for the LDAP channel
• REST Channel Guide — Configuration and usage for the REST channel
• GraphQL Channel Guide — Configuration and usage for the GraphQL channel
• MCP Channel Guide — AI coding assistant integration via Model Context Protocol
• Failures — Error codes, retry guidance, and troubleshooting
• Observability — Metrics, traces, and operational playbooks
• Configuration Guide — General configuration reference