Skip to content
comrce Hubcomrce HubAdmin Guide

Create or edit an API client

For: comrce staff with the Super Admin roleRequires: The Super Admin roleScreenshots show sample data

The API client form registers a partner application or changes an existing registration. A Super Admin enters a display name, the scopes, the redirect addresses and two switches. After the first save, comrce Hub shows the client secret once.

Open the form from API Keys. Use Create New Client for a new client, or Edit in a row for an existing one.

What you can do here

Section titled “What you can do here”

The screen at a glance

Section titled “The screen at a glance”
The "New API client" tab with the heading "Create New SSO API Client". At the top the "Client ID" field is greyed out and already holds the generated ID a81d5e07-2c3b-4f96-8e14-6b9f0c2d7a58, which cannot be edited. Below it the empty, highlighted "Display Name" field is required. Then come two unticked checkboxes, "Allow silent authentication" and "Allow client credentials flow", the "Allowed scopes" picker with the note "Identity (openid) is always required." and the placeholder "Select optional scopes", and the first empty "Redirect URI" row with an "Add Redirect URI" button. The Save button further down stays disabled until the form is valid.The "New API client" tab with the heading "Create New SSO API Client". At the top the "Client ID" field is greyed out and already holds the generated ID a81d5e07-2c3b-4f96-8e14-6b9f0c2d7a58, which cannot be edited. Below it the empty, highlighted "Display Name" field is required. Then come two unticked checkboxes, "Allow silent authentication" and "Allow client credentials flow", the "Allowed scopes" picker with the note "Identity (openid) is always required." and the placeholder "Select optional scopes", and the first empty "Redirect URI" row with an "Add Redirect URI" button. The Save button further down stays disabled until the form is valid.
The client ID is generated for you. Start with the display name partners and customers will recognise.
What this screenshot shows
Screen
Create New SSO API Client
Highlighted
“Display Name”: names the client in the list and on the customer's consent screen
Also visible
Client ID: generated, read-only; Checkboxes unticked, scopes picker empty, one empty redirect URI row
Purpose
the create form as it opens
RegionWhat it showsWhat you do there
HeadingCreate New SSO API Client or Edit SSO API ClientOrientation
Identity fieldsClient ID (read-only) and Display NameName the client
SwitchesAllow silent authentication and Allow client credentials flowAllow silent sign-in or machine access
ScopesAllowed scopesChoose what may be requested
AddressesRedirect URIs and Post-logout Redirect URIs (optional)Enter the partner’s URLs
BottomSaveCreate or update the client

Fill in the create form

Section titled “Fill in the create form”
  1. On API Keys, select Create New Client. The form opens with a generated client ID.
  2. Type the display name, for example Reporting export.
  3. Tick the switches the partner needs. Leave them off otherwise.
  4. Choose scopes in Allowed scopes.
  5. Enter the redirect URI, for example https://reports.example.net/auth/callback. Add more rows with Add Redirect URI.
  6. Select Save.
The complete create form, filled in for the client "Reporting export". The Client ID field shows the generated ID a81d5e07-2c3b-4f96-8e14-6b9f0c2d7a58, "Allow silent authentication" is unticked and "Allow client credentials flow" is ticked. "Allowed scopes" shows two chosen scopes, Organization and Write external events. "Redirect URI 1" holds https://reports.example.net/auth/callback, and the post-logout row is empty because it is optional. At the bottom the highlighted Save button is now enabled. Saving creates the client and opens a dialog with its client secret.The complete create form, filled in for the client "Reporting export". The Client ID field shows the generated ID a81d5e07-2c3b-4f96-8e14-6b9f0c2d7a58, "Allow silent authentication" is unticked and "Allow client credentials flow" is ticked. "Allowed scopes" shows two chosen scopes, Organization and Write external events. "Redirect URI 1" holds https://reports.example.net/auth/callback, and the post-logout row is empty because it is optional. At the bottom the highlighted Save button is now enabled. Saving creates the client and opens a dialog with its client secret.
A machine client for exports needs client credentials, a narrow scope set and one redirect URI.
What this screenshot shows
Screen
Create New SSO API Client
Highlighted
“Save”: creates the client and shows its secret once
Also visible
Display name: Reporting export; Client credentials ticked, silent authentication unticked; Scopes: Organization, Write external events; Redirect URI 1: https://reports.example.net/auth/callback
Purpose
a filled create form ready to save

The button becomes active only when the form is valid and the scope list has loaded. An address without a scheme is refused right away:

The create form scrolled to the redirect section. The field "Redirect URI 1" contains reports.example.net/auth/callback without the https scheme, and the highlighted red message "Redirect URI must be valid." appears under it. The Save button further down stays disabled while the error is shown. A redirect URI must be an absolute address with a scheme such as https, because comrce Hub sends the signed-in user back to exactly this address after sign-in.The create form scrolled to the redirect section. The field "Redirect URI 1" contains reports.example.net/auth/callback without the https scheme, and the highlighted red message "Redirect URI must be valid." appears under it. The Save button further down stays disabled while the error is shown. A redirect URI must be an absolute address with a scheme such as https, because comrce Hub sends the signed-in user back to exactly this address after sign-in.
Redirect URIs must be absolute addresses including the https scheme. The form rejects anything else.
What this screenshot shows
Screen
Create New SSO API Client
Highlighted
“Redirect URI must be valid.”: blocks saving until the address is corrected
Also visible
Value without scheme: reports.example.net/auth/callback; Save disabled
Purpose
the validation message for a redirect URI without a scheme

Choose scopes

Section titled “Choose scopes”

Open Allowed scopes and select options. Each selected option shows a tick, and the field lists the labels. A search box at the top filters the options. Close the list with Esc or a click outside. Identity (openid) is always included and is not in the list.

Customers approve exactly the scopes you choose here, so pick only what the partner’s integration uses.

The create form with "Reporting export" typed into Display Name and the "Allowed scopes" picker open below the note "Identity (openid) is always required." The drop-down has a search box and lists the optional scopes by their labels in alphabetical order: "Billing address", "Email", "Organization" (already ticked), "Profile", "Stay signed in", "Tool permissions" and the highlighted "Write external events". Identity (openid) is not in the list because every client gets it automatically. Selecting an option adds it to the client's allowed scopes.The create form with "Reporting export" typed into Display Name and the "Allowed scopes" picker open below the note "Identity (openid) is always required." The drop-down has a search box and lists the optional scopes by their labels in alphabetical order: "Billing address", "Email", "Organization" (already ticked), "Profile", "Stay signed in", "Tool permissions" and the highlighted "Write external events". Identity (openid) is not in the list because every client gets it automatically. Selecting an option adds it to the client's allowed scopes.
Pick only the scopes the partner application needs. Identity (openid) is always included.
What this screenshot shows
Screen
Create New SSO API Client
Highlighted
“Write external events”: adds the comrce.external-events.write scope to the client
Also visible
7 optional scopes, Organization selected; openid not listed; always included
Purpose
choosing the scopes a client may request

Copy the client secret

Section titled “Copy the client secret”

After saving, the dialog Client Secret opens. Select Copy. The button briefly shows Copied!, and the message Secret copied! confirms. Then select Close. It closes the dialog and the create tab and refreshes the list. Closing the dialog any other way, with Esc or a click outside, also loses the secret.

The dialog that opens after saving the new client. Its highlighted title reads "Client Secret", followed by "This is your only chance to copy the client secret. It will not be shown again!" A code box holds the secret, shown here as the placeholder REDACTED because these screenshots never contain real secrets, with a Copy button beside it. Under it the red warning reads "Keep your client secret secure. You won't be able to view it again." The wide "Close" button at the bottom closes the dialog and the create tab and refreshes the list.The dialog that opens after saving the new client. Its highlighted title reads "Client Secret", followed by "This is your only chance to copy the client secret. It will not be shown again!" A code box holds the secret, shown here as the placeholder REDACTED because these screenshots never contain real secrets, with a Copy button beside it. Under it the red warning reads "Keep your client secret secure. You won't be able to view it again." The wide "Close" button at the bottom closes the dialog and the create tab and refreshes the list.
Copy the client secret now. It is shown exactly once and cannot be displayed again.
What this screenshot shows
Screen
Create New SSO API Client
Highlighted
“Client Secret”: shows the generated client secret once
Also visible
Secret box (placeholder REDACTED in sample data) with Copy button; Warning: "Keep your client secret secure. You won't be able to view it again."; Final button Close
Purpose
the one-time client secret

Edit a client

Section titled “Edit a client”

Select Edit in a list row. The edit tab shows the current values and a red notice about removing scopes. Change what you need and select Save. The message Client updated! appears, the list refreshes and the tab closes. If the change is refused, Update failed! appears above the form and the tab stays open.

The edit tab for the client "Nordwind ERP connector", titled with its client ID, under the heading "Edit SSO API Client". The Client ID field is greyed out with 3f2b8c41-7d6e-4a19-9c52-1e8a7b0d4f63, Display Name holds "Nordwind ERP connector", "Allow silent authentication" is ticked and "Allow client credentials flow" is not. Below the checkboxes the highlighted red text reads "Disabling client credentials or removing scopes revokes all active user and machine sessions for this client." The scopes picker shows the client's five optional scopes, followed by its redirect URI https://erp.example.com/oauth2/callback.The edit tab for the client "Nordwind ERP connector", titled with its client ID, under the heading "Edit SSO API Client". The Client ID field is greyed out with 3f2b8c41-7d6e-4a19-9c52-1e8a7b0d4f63, Display Name holds "Nordwind ERP connector", "Allow silent authentication" is ticked and "Allow client credentials flow" is not. Below the checkboxes the highlighted red text reads "Disabling client credentials or removing scopes revokes all active user and machine sessions for this client." The scopes picker shows the client's five optional scopes, followed by its redirect URI https://erp.example.com/oauth2/callback.
Editing keeps the client ID and secret. Removing scopes or client credentials signs everyone out of that client.
What this screenshot shows
Screen
Edit SSO API Client
Highlighted
“Disabling client credentials or removing scopes revokes all active user and machine sessions for this client.”: warns that reducing authority revokes the client's sessions and tokens
Also visible
Client: Nordwind ERP connector, silent authentication on; Scopes: Profile, Email, Stay signed in, Organization, Billing address
Purpose
the edit form with its revocation warning

Removing a scope, or unticking client credentials, ends every approval and token of the client in the same save. Adding scopes or changing the name and the URIs ends nothing.

Every control, explained

Section titled “Every control, explained”

Allowed scopes

Section titled “Allowed scopes”
Where

The picker Allowed scopes with the placeholder Select optional scopes. Above it is the note Identity (openid) is always required.

What

Seven options:

  • Profile
  • Email
  • Stay signed in
  • Organization
  • Billing address
  • Tool permissions
  • Write external events

The picker is disabled while the list loads. If loading fails, Could not load the available scopes. and Retry appear, and saving is blocked.

Why

This list is what customers are asked to approve.

Allow client credentials flow

Section titled “Allow client credentials flow”
Where

Second checkbox, Allow client credentials flow, off by default.

What

On: the partner’s server gets tokens for the client itself, with the ID and secret alone. Unticking it on an existing client ends all of its sessions and tokens.

Why

Services that run without a user, such as an export, need an identity of their own.

Allow silent authentication

Section titled “Allow silent authentication”
Where

First checkbox, Allow silent authentication, off by default.

What

On: the partner may sign users in without showing a page. This works only for users who approved this client before, for the same organization and scopes. Off: such requests fail.

Why

Embedded dashboards need sign-in in the background. Everything else is safer with a visible step.

Post-logout Redirect URIs

Section titled “Post-logout Redirect URIs”
Where

The section Post-logout Redirect URIs (optional) with Add Post-logout Redirect URI.

What

Optional. Empty rows are ignored, and filled rows must be valid (Post logout URI must be valid.). In the edit form, an emptied list is not saved, and the old addresses remain. To change them, enter at least one new address.

Why

Users who sign out through the partner land back on the partner’s page.

Redirect URIs

Section titled “Redirect URIs”
Where

The section Redirect URIs, with one field per address, a remove button beside each and Add Redirect URI.

What

At least one absolute URL. An invalid one shows Redirect URI must be valid., an empty one Redirect URI is required.. The last remaining row cannot be removed. The grey example text in an empty field is a placeholder, not a value.

Why

comrce Hub returns sign-in results only to these addresses.

Client ID

Section titled “Client ID”
Where

First field, Client ID, greyed out.

What

Generated when the create form opens and never editable. In the rare case that the ID already exists, saving shows Client with this Id already exists.

Why

A random ID cannot be guessed and never clashes with an existing client.

Other controls on this page

ControlWhat it doesWhy
Display NameRequired plain text. Empty shows Display name is required.. The name appears in the list and when customers approve access.Customers approve access by a name they recognise.
SaveCreates the client and opens the secret dialog, or saves the edit and closes the tab. It stays disabled while the form is invalid or unchanged, and while the scopes are loading or failed to load.An incomplete client would leave the partner unable to sign anyone in.

Who sees what

Section titled “Who sees what”
PartWho sees it
Both form tabsSuper Admin only
The notice Disabling client credentials or removing scopes revokes all active user and machine sessions for this client.Edit tab only
The secret dialogOnly right after creating, once

What you need to know

Section titled “What you need to know”
TopicFact
DefaultsBoth switches off, Identity only, one empty redirect row, one empty post-logout row.
Secret43 characters, never in the edit form, no renewal.
Leaving with changesClosing the tab with unsaved changes asks for confirmation first.
Edit loadingThe edit tab loads the client by its ID. Open it from the list row.

Frequently asked questions

Section titled “Frequently asked questions”

Create

Section titled “Create”

Why can’t I type into the Client ID field?

Section titled “Why can’t I type into the Client ID field?”

comrce Hub generates the client ID when the create form opens. Client ID stays read-only in the create and the edit form. Give the partner that generated ID together with the secret from the dialog.

Why does the form say Identity (openid) is always required?

Section titled “Why does the form say Identity (openid) is always required?”

Every API client needs the Identity scope, so that comrce Hub can tell the partner who signed in. It is added automatically and does not appear in the Allowed scopes picker. Choose only the optional scopes.

What happens if I close the secret dialog by accident?

Section titled “What happens if I close the secret dialog by accident?”

The client exists, but its secret cannot be shown again. Delete the client under API Keys and create a new one. Copy the new secret with Copy before you close the dialog.

What does Close in the secret dialog do?

Section titled “What does Close in the secret dialog do?”

Close closes the dialog Client Secret and the create tab. It also refreshes the API client list, so the new client appears there. The secret is gone afterwards, so copy it with Copy first.

Edit

Section titled “Edit”

Can I change the secret of an existing client?

Section titled “Can I change the secret of an existing client?”

No. The edit form shows no secret and has no renewal button. Create a second client with the same settings and let the partner switch to the new ID and secret. Delete the old client afterwards.

Will saving the edit form sign customers out?

Section titled “Will saving the edit form sign customers out?”

Only if you removed a scope or unticked Allow client credentials flow. In that case comrce Hub ends every approval and token of the client. Customers approve again at their next sign-in. Other changes sign nobody out.

Why are deleted post-logout URIs back after saving?

Section titled “Why are deleted post-logout URIs back after saving?”

The edit form does not save an empty Post-logout Redirect URIs (optional) list. The previous addresses stay on the client. Enter at least one new post-logout address in the edit form to replace the old ones.

Validation

Section titled “Validation”

Why is Save still disabled?

Section titled “Why is Save still disabled?”

Save needs a display name and at least one valid redirect URI. The scope list must have loaded, and something must have changed. Look for red messages under the fields. Also look for Could not load the available scopes. under the scope picker.

Troubleshooting

Section titled “Troubleshooting”
SymptomWhat to check
Redirect URI must be valid.Add the scheme: https://….
Could not load the available scopes.Select Retry. Reload the console if it persists.
Client with this Id already existsClose the create tab and open it again from the list to get a new ID.
Update failed! above the edit formCorrect the fields with red messages and save again.
Could not load the API client. fills the edit tabThe client could not be loaded. A teammate may have deleted it, or the connection failed. Close the tab and open the client again from the list.
The secret dialog closed before copyingDelete the client and create a new one.
Section titled “Related”