Integration Management

Goal

Register, configure, and manage OAuth 2.0 (OpenID Connect) and SAML client applications that integrate with the Keymate platform. By the end of this guide, you will know how to create clients through the three-step wizard, update their capability and access settings, manage client-scoped roles, assign clients to tenants, and delete clients individually or in bulk.

Audience

This guide is for platform administrators and integration engineers who manage application registrations in the Keymate Admin Console. You should be familiar with the basics of OAuth 2.0 / OpenID Connect or SAML protocols.

Prerequisites

• Access to the Keymate Admin Console
• The clients:read scope to view and list clients
• The clients:create scope to register new clients
• The clients:update scope to modify existing clients
• The clients:delete scope to remove clients

Before You Start

In Keymate, a client represents an application registered with the identity provider for authentication and authorization. Each client holds protocol settings, redirect URIs, and capability flags that control how the application interacts with the platform.

Keymate supports two client protocols:

Protocol	Value	Description
OpenID Connect	openid-connect	OAuth 2.0-based protocol for modern web, mobile, and API applications. Selected by default when creating a new client.
SAML	saml	XML-based protocol for enterprise single sign-on (SSO) integrations.

Clients can be either public or confidential:

• Public clients cannot securely store a client secret (for example, single-page applications or mobile apps). Authorization services and service accounts are unavailable for public clients.
• Confidential clients authenticate with a client secret and can use authorization services and service account roles.

Steps

1. Browse the client list

Navigate to Integrations > Clients in the Admin Console sidebar. The clients list page is available at the route /integrations/clients.

The list displays the following columns for each client:

Column	Description
Client ID	The unique identifier for the client. Click the ID to open the client detail page.
Name	The display name of the client.
Description	A short description of the client's purpose.
Protocol	The client protocol (openid-connect or saml).
Client Authentication	Whether the client is Public or Confidential.
Enabled	The enabled or disabled status of the client.

Use the search bar at the top of the list to filter clients by name or client ID. You can also filter by Tenant using the tenant dropdown filter. The list supports pagination with a default page size.

Each row provides the following actions through the row action menu:

• View -- Open the client detail page
• Export -- Download the client configuration as a JSON file (requires clients:read)
• Delete -- Remove the client (requires clients:delete)

2. Create a new client

1. On the clients list page, click the Create dropdown button in the top-right corner.
2. Select the Create option to open the creation wizard, or select Import to populate the wizard from an existing JSON configuration file.

The creation wizard guides you through three steps:

Step 1 -- General Settings

Configure the client's identity and protocol.

Field	Required	Description
Client ID	Yes	A unique identifier for the client (maximum 255 characters).
Name	No	A human-readable display name.
Protocol	No	Select OpenID Connect or SAML. Defaults to OpenID Connect.
Description	No	A brief description of the client's purpose.
Always Display in Console	No	Toggle to control whether this client always appears in the account console. Defaults to off.

Step 2 -- Capability Config

Configure the client's authentication type and OAuth 2.0 / OpenID Connect flow toggles.

Setting	Default	Description
Client Authentication	Off (public)	Turn on to make the client confidential. Turning this off disables authorization services and service accounts.
Authorization	Off	Enable fine-grained authorization services. Available for confidential clients only. Enabling this automatically enables service accounts.
Standard Flow	On	Enable the OAuth 2.0 Authorization Code flow.
Direct Access Grants	On	Enable the Resource Owner Password Credentials grant.
Implicit Flow	Off	Enable the OAuth 2.0 Implicit flow.
Service Accounts	Off	Enable service account roles (client credentials grant). Available for confidential clients only.

tip

When you enable Authorization, the wizard automatically enables Service Accounts because authorization services require a service account to function.

Step 3 -- Login Settings (optional)

Configure the URLs that the client uses during authentication flows.

Field	Description
Root URL	The base URL appended to relative redirect URIs.
Home URL	The default URL the application uses after login.
Admin URL	The URL for backchannel administration requests.
Valid Redirect URIs	The allowed redirect URIs after login. Click the add button to add multiple URIs.
Web Origins	The allowed CORS origins. Click the add button to add multiple origins.

3. After completing the wizard steps, click Finish to create the client. The Admin Console redirects you to the clients list page.

3. View client details

Click a Client ID link in the clients list, or use the View action from the row action menu. The detail page is available at the route /integrations/clients/{id}.

The detail page organizes client information into three tabs:

• General Settings -- Shows the client ID, name, description, protocol, enabled status, and the always-display-in-console flag.
• Access Settings -- Shows the root URL, home URL, valid redirect URIs, and web origins.
• Capability Config -- Shows the client authentication type, authorization services status, and authentication flow toggles (standard flow, direct access grants, implicit flow, service accounts).

From the detail page actions menu, you can:

• Export the client configuration as a JSON file
• Delete the client

4. Edit client settings

1. Open the client detail page.
2. Navigate to the tab for the settings you want to change (General Settings, Access Settings, or Capability Config).
3. Click the Edit button (pencil icon) in the top-right corner of the tab content. A drawer panel opens with the editable form.
4. Make your changes and click the submit button in the drawer footer.

Editing General Settings:

You can update the client name, description, protocol, enabled status, and the always-display-in-console flag. The Client ID field is read-only and cannot be changed after creation.

Editing Access Settings:

You can update the root URL, home URL, valid redirect URIs, and web origins. Use the add and delete buttons to manage the list of URIs and origins.

Editing Capability Config:

You can toggle the client authentication type and individual authentication flows. The same dependency rules apply as during creation: switching to a public client disables authorization services and service accounts.

5. Manage client roles

Client roles are application-specific roles that you define on a client. To manage roles:

1. Navigate to the client edit page at the route /integrations/clients/{id}/edit.
2. The edit page displays a Client Form for basic settings and a Roles card below it.
3. In the Roles section, you see all existing roles for the client. Existing role names are read-only.
4. Click the Add button to add a new role. Enter a role name in the new input field.
5. To remove an existing role, delete it from the list.
6. Click Update to save all role changes at once.

The system processes role changes as a bulk operation -- it deletes removed roles and creates new roles in a single save action.

note

Role names must be unique within a client. Each role requires a name of at least 1 character and a maximum of 255 characters.

6. Assign a client to a tenant

You can associate a client with a tenant in two ways:

• During creation: When creating a client from the tenant detail page (Settings > Tenants > select a tenant > Clients), the tenant assignment is set automatically.
• After creation: Use the tenant management interface to assign an existing client to a tenant. Navigate to Settings > Tenants, open the target tenant, and assign the client from the Clients tab.

To revoke a client from a tenant, use the tenant management interface to remove the client association.

7. Delete clients

Single delete:

1. In the clients list, click the Delete action in the row action menu for the target client, or click Delete from the client detail page actions menu.
2. A confirmation dialog appears. Type the client name to confirm the deletion.
3. Click Delete to remove the client.

Bulk delete:

1. In the clients list, select the checkboxes next to the clients you want to remove (requires clients:update permission to see selection checkboxes).
2. Click the Bulk Delete action in the bulk actions bar.
3. Confirm the deletion in the dialog. The dialog shows the number of clients selected for deletion.
4. The system returns a summary with the count of successful and failed deletions.

warning

Deleting a client is irreversible. All tokens issued by the client become invalid, and any services relying on the client lose access. Verify that no active applications depend on the client before deleting it.

Validation Scenario

Scenario

Create an OpenID Connect client with the standard flow enabled, verify it appears in the list, edit its redirect URIs, and verify the update.

Expected Result

The new client appears in the clients list with the correct protocol, authentication type, and enabled status. After editing, the updated redirect URIs appear in the Access Settings tab.

How to Verify

1. Navigate to Integrations > Clients and click Create.
2. In Step 1 (General Settings), enter acme-web-app as the Client ID, set the name to Acme Web Application, and keep the protocol as OpenID Connect.
3. In Step 2 (Capability Config), verify that Standard Flow is enabled (on by default). Leave Client Authentication off (public client).
4. Skip Step 3 (Login Settings) and click Finish.
5. In the clients list, search for acme-web-app. Verify the client appears with protocol openid-connect, authentication type Public, and status Enabled.
6. Click the client ID to open the detail page. Go to the Access Settings tab and click the Edit button.
7. In the drawer, add https://app.example.com/callback as a valid redirect URI and click Save.
8. Close the drawer and confirm that the Access Settings tab displays the new redirect URI.

Troubleshooting

Issue	Possible Cause	Resolution
Cannot see the Create button on the clients list page	Your account lacks the clients:create scope	Ask a platform administrator to grant the clients:create scope to your role.
Authorization toggle is disabled in Step 2	The client is configured as a public client	Enable Client Authentication first to make the client confidential, then enable Authorization.
Service Accounts toggle is disabled	The client is configured as a public client	Enable Client Authentication to unlock the Service Accounts toggle.
Delete button requires typing the client name	This is a safety mechanism to prevent accidental deletion	Type the exact client name as displayed in the confirmation dialog.
Client does not appear in the list after creation	The list may be filtered by a tenant or search term	Clear all filters and search terms, then refresh the page.
Bulk delete reports partial failures	Some clients may be protected or referenced by active sessions	Review the failure count and check whether the failed clients have active dependencies.

Next Steps

After registering and configuring your clients, consider these follow-up tasks:

• Configure OAuth client management for advanced OAuth 2.0 settings and client credential rotation.
• Set up tenant management to organize clients across tenants.
• Review permission management to define fine-grained access policies for your clients.
• Explore import, export, and migration to back up client configurations or migrate them between environments.

Related Docs

OAuth Client Management

Advanced OAuth 2.0 client settings, secrets, and credential rotation.

Tenant Management

Organize clients, users, and resources across isolated tenants.

User and Role Management

Manage users and realm-level roles that interact with clients.

Import, Export, and Migration

Export client configurations and migrate between environments.