Dynamic Client Registration Management with GraphQL API

The DCR Management GraphQL API provides a programmatic interface for managing dynamically registered OAuth clients. This API enables administrators and management clients to list, read, and update client registrations through a flexible GraphQL endpoint that surfaces as a sub-path on the Dynamic Client Registration endpoint.

When Dynamic Client Registration (DCR) is enabled in a Token profile, a GraphQL API becomes available at the /graphql sub-path of the DCR endpoint. This API provides methods to list and read all clients registered through DCR, as well as operations to change client status. Access to the API requires an authorization manager to be configured on the Token profile.

The GraphQL API complements the standard RFC 7592 DCRM endpoints by providing more flexible querying capabilities for managing multiple dynamically registered clients.

Use Cases#

The DCR Management GraphQL API enables programmatic client management scenarios for administrators and automated systems.

Common use cases include:

  • Bulk Client Management: Query and manage multiple dynamically registered clients simultaneously through a single API endpoint, rather than making individual REST calls per client
  • Client Discovery and Auditing: List all dynamically registered clients with filtering and pagination capabilities to audit client registrations and monitor client populations
  • Administrative Oversight: Enable management clients to obtain tokens with the dcrm scope and use them to manage any dynamically registered client until the token expires or is revoked
  • Client Status Management: Change the status of dynamically registered clients (enable, disable) without requiring the client’s own registration access token
  • Integration with Admin Tools: Build custom administrative dashboards and management tools that integrate with the Curity Identity Server‘s client registration system through GraphQL queries and mutations
  • Automated Client Lifecycle: Implement automated workflows for client provisioning, updates, and deprovisioning as part of application deployment pipelines

Getting Started#

To use the DCR Management GraphQL API, ensure Dynamic Client Registration is enabled on your Token profile and an authorization manager is configured to control access.

Obtaining an Access Token#

To work with the GraphQL API, obtain an access token that meets the requirements defined by the authorization manager configured on the profile. Most commonly, the token needs to contain a specific scope (such as dcrm for management clients) to pass authorization.

Management clients can request a token with the dcrm scope through a client credentials flow:

POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=dcrm

The resulting token can be used to manage any dynamically registered client until it expires (default 28 days) or is revoked.

When a client is updated by a DCRM Management Client using a token with the dcrm scope, the client’s client_secret is not rotated. The management client can set a specific secret by sending the client_secret parameter in an update request.

Accessing the GraphQL Endpoint#

The GraphQL endpoint is available at the DCR endpoint path with /graphql appended. For example, if the DCR endpoint is at https://curity.example.com/dcr, the GraphQL endpoint is at https://curity.example.com/dcr/graphql.

Include the access token in the Authorization header using the Bearer authentication scheme:

POST /dcr/graphql HTTP/1.1
Host: curity.example.com
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "query": "query { dynamicallyRegisteredClients { edges { node { client_id client_name } } } }"
}

Introspecting the Schema#

Most GraphQL tools allow schema introspection when provided with a valid access token. The schema exposes two top-level types:

  • Query: Used for reading data (listing and retrieving client information)
  • Mutation: Used for updating data (changing client status and configuration)

Configure your GraphQL tool to include the access token in request headers to introspect the schema and explore available operations.

Schema introspection can be disabled in production environments for security reasons through the GraphQL configuration settings.

Using Queries#

The API provides queries to retrieve single clients or multiple clients with cursor-based pagination:

query ListClients {
  dynamicallyRegisteredClients(sorting: { sortBy: created, sortOrder: ASCENDING }) {
    edges {
      node {
        client_id
        client_name
        redirect_uris
      }
    }
    pageInfo {
      endCursor
      hasNextPage
    }
    totalCount
  }
}

The pagination model loosely follows the Relay GraphQL Connection Specification, making it familiar to developers experienced with GraphQL APIs.

GraphQL Errors#

Errors are represented according to the GraphQL specification. The extensions object may contain a classification key with a stable identifier for the error type:

{
  "errors": [
    {
      "message": "At least 1 filter key must be defined",
      "locations": [],
      "extensions": {
        "classification": "operation-not-supported",
        "not-supported-cause": "FILTERING_ABSENT"
      }
    }
  ]
}

The message key contains error descriptions intended for developers, not end users. These messages are not localized and may change between Curity Identity Server versions or based on configuration settings.

DCR Management Clients#

Management clients provide a powerful way to administer dynamically registered clients through the GraphQL API. Unlike standard dynamically registered clients that can only manage themselves using single-use registration access tokens, management clients can oversee any dynamically registered client in the system.

Management clients differ from standard dynamically registered clients in several ways:

  • Scope-Based Access: Request tokens with the dcrm scope rather than using registration access tokens obtained during client registration
  • Broad Management Capabilities: Can manage any dynamically registered client, not just themselves, enabling centralized administration
  • Long-Lived Tokens: Use tokens that remain valid until expiration (default 28 days) or revocation, rather than single-use registration access tokens that expire after one operation
  • Client Secret Preservation: Do not rotate client secrets when performing updates—secrets remain unchanged unless explicitly set via the client_secret parameter in an update request

This approach enables automated management workflows and administrative tools that can query, update, and monitor all dynamically registered clients without requiring each client’s individual registration access token.

Access Control#

Access to the DCR Management GraphQL API is controlled through authorization managers configured on the Token profile. This ensures that only authorized clients and users can perform management operations on dynamically registered clients.

Key access control considerations:

  • Dynamically Registered Clients Only: Only clients registered through DCR can be managed via the GraphQL API. Statically configured clients are not accessible through this endpoint.
  • Authorization Manager Requirements: The authorization manager configured on the Token profile determines which access tokens can access the API and what operations they can perform.
  • Scope Requirements: Tokens typically need to contain specific scopes (such as dcrm for management operations) to pass the initial authorization step.
  • Groups Authorization: If using the Groups Authorization Manager, ensure the access token contains a groups claim with user groups that match the authorization manager rules. This typically requires mapping the groups claim for access tokens in the token profile configuration.

For detailed information on configuring authorization managers and setting up claim mappings, see the Authorization Managers documentation.

Learn More#

To learn more about the DCR Management with GraphQL API and related concepts:

Was this helpful?