API clients and third-party sign-in

For: comrce staff with the Super Admin role who connect partner applications·Requires: The Super Admin role·Screenshots show sample data

An API client lets a partner application sign customers in with their comrce Hub account. Typical partners are ERP connectors and warehouse dashboards. The client sets where users return and which customer data the application may request. It also sets whether the application may act on its own. You create and maintain API clients under API Keys.

What it does

comrce Hub refuses sign-in requests from an outside application it does not know. A partner who wants “sign in with comrce Hub” therefore needs a registration. Someone at comrce decides how much the application may see.

An API client is a confidential sign-in client. It has a generated client ID, a secret shown exactly once and at least one redirect URI. It also has a set of allowed scopes out of eight. With it:

• Customers sign in to the partner application with their comrce Hub account. They approve the request on a consent page that names the client. API clients in the customer sign-in.
• You decide what the application may read, from the user’s identity to the organization’s billing address. The scope setting.
• A partner service can fetch tokens for itself, without a signed-in user, to send external events to comrce Hub. The machine switch.
• Customers who already approved an application can be signed in silently, without a second prompt. The silent sign-in switch.
• You can narrow a client later. comrce Hub then ends every session and token the client holds. Editing a client.

Every create, update and delete is recorded under Logs, with the acting Super Admin and the client’s settings. API clients in the logs.

Before you start

Requirement	Details
Role	The Super Admin role. Other staff roles see no API Keys entry. Ask a Super Admin under Hub Team if you need the role.
The partner’s redirect URIs	The exact addresses the partner application receives users on after sign-in, as absolute URLs with https://. Ask for every environment the partner uses, such as production and staging.
The partner’s post-logout URIs (optional)	The addresses users land on after signing out through the partner.
The data the partner needs	Which of the eight scopes the integration needs. Agree on this with the partner first, because customers are asked to approve exactly this list.
A secure channel to the partner	The client secret is shown once. Prepare a password manager share or another secure channel before you save.
Cost	None. API clients have no quota or usage limit.

Good to know

An API client is not a key for calling admin functions. It lets an outside application sign comrce Hub customers in and, with client credentials, submit external events. Staff accounts cannot sign in to partner applications at all.

API clients live under API Keys, the first sidebar entry, which only staff with the Super Admin role see.

What this screenshot shows

Screen

API Keys

Highlighted

“API Keys”: opens the API Keys tab

Also visible

2 API clients: Nordwind ERP connector, Warehouse dashboard; Signed in with the Super Admin role

Purpose

entry point of API client management

Understanding scopes and grant types

A scope is one kind of data or permission the application may request. comrce Hub offers eight. Identity (openid) is always on and does not appear in the picker. Partners often name scopes by their technical name, so the table gives both.

Scope label	Technical scope	What the application receives	Typical partner
Identity	openid	Identify you to the application.	every client
Profile	profile	Share your name, username, and language.	a dashboard that greets the user
Email	email	Share your email address and verification status.	an ERP that matches users by email
Stay signed in	offline_access	Allow the application to refresh access while you are away.	any app that keeps users signed in
Organization	comrce.organization	Share your selected organization’s ID and name.	anything that stores data per seller
Billing address	comrce.billing	Share your selected organization’s invoice address.	invoicing and ERP tools
Tool permissions	comrce.permissions	Share your role and current permissions for the selected organization.	tools that mirror comrce Hub permissions
Write external events	comrce.external-events.write	Allows the application to submit external events to comrce Hub.	services that report activity back

How comrce Hub decides

• Every client may use the normal browser sign-in. The user signs in at comrce Hub, approves the request and returns to one of the redirect URIs.
• Stay signed in also allows refreshing access. The application can renew access without sending the user through sign-in again. Removing the scope takes that ability away.
• Allow client credentials flow adds machine access. The partner’s server then gets tokens for the client itself, with no user involved.
• A redirect URI must match exactly. comrce Hub sends users back only to an address on the client’s list.
• Silent sign-in needs two things. The client must allow silent authentication. The user must also have approved this client before, for the same organization and scopes. Otherwise the request fails, and the partner has to show the normal sign-in.

What does not get signed in

• Staff accounts. A user with a comrce staff role is refused, and the logs record a failed sign-in.
• Customers without a selected organization. Only customer accounts signed in with an organization can approve a partner application.
• Requests for a scope the client does not allow, or for a redirect URI that is not on its list.
• Silent sign-in requests to a client without Allow silent authentication, or for scopes the user never approved.

Setting it up in five steps

1. Open the form. Go to API Keys and select Create New Client. A new tab opens with a generated Client ID.

2. Name the client. Type the name customers will recognise into Display Name, for example Reporting export. The consent page shows this name.

3. Choose scopes and switches. Open Allowed scopes and select what the partner needs. Tick Allow client credentials flow only for a service that works on its own. Tick Allow silent authentication only if the partner asked for silent sign-in.

   

   Each scope unlocks one kind of data. Organization shares the ID and name of the customer's selected organization.

   What this screenshot shows

   Screen

   Create New SSO API Client

   Highlighted

   “Organization”: allows the comrce.organization scope

   Also visible

   7 optional scopes; openid not listed

   Purpose

   choosing scopes for a new client

4. Enter the addresses. Fill in the first redirect URI and add more with Add Redirect URI. Add post-logout URIs if the partner gave you any. Select Save.

   

   Tick client credentials only for services that act on their own, such as a nightly export.

   What this screenshot shows

   Screen

   Create New SSO API Client

   Highlighted

   “Allow client credentials flow”: adds the client_credentials grant

   Also visible

   Scopes: Organization, Write external events; Redirect URI 1: https://reports.example.net/auth/callback; Save enabled

   Purpose

   a machine client configured for the client credentials grant

5. Copy the secret. The Client Secret dialog opens. Select Copy and send the secret and the client ID to the partner through your secure channel. Then close the dialog with Close.

   

   Use Copy and hand the secret to the partner through a secure channel before you close the dialog.

   What this screenshot shows

   Screen

   Create New SSO API Client

   Highlighted

   “Copy”: copies the client secret to the clipboard

   Also visible

   Secret box (REDACTED in sample data); Final button Close

   Purpose

   the one-time secret after creating a client

The order from the first test to production is in Add a new partner and their offer to the Marketplace. Adding scopes later never signs anyone out.

Every setting, explained

Each setting appears in the create and the edit form. The settings that need the most care come first.

Allowed scopes

Where

The picker Allowed scopes with the note Identity (openid) is always required. Pick options in the drop-down. The field lists them separated by commas. Saved with Save.

What

Seven optional scopes, listed by label in alphabetical order. Identity (openid) is always added, and a new client starts with Identity only.

If the scope list cannot be loaded, the picker shows Could not load the available scopes. with Retry. Saving is blocked until the list loads. Removing a scope from an existing client ends every session and token of that client.

Why

Customers are asked to approve exactly this list. Fewer scopes mean a shorter consent page and less data in a partner’s hands.

Allow client credentials flow

Where

The second checkbox, Allow client credentials flow. Off by default. Saved with Save.

What

On: the partner’s server can request tokens with the client ID and secret alone. The tokens are for the client itself, with its allowed scopes. With Write external events, such tokens can write external events. Off: only user sign-ins are possible. Turning it off on an existing client ends every session and token the client holds.

Why

A nightly export or a service that reports events has no user in front of it. Client credentials give it its own identity instead of a borrowed user account.

Allow silent authentication

Where

The first checkbox, Allow silent authentication. Off by default. Saved with Save.

What

On: the partner may ask comrce Hub to sign a user in without showing any page. This succeeds only when the user is signed in to comrce Hub with an organization. The user must also have approved this client for that organization and the requested scopes before.

Off: such requests fail with the answer “interaction required”, and the logs record the failed attempt.

Why

Dashboards embedded in other tools want to sign users in in the background. With the switch off, every sign-in has a visible step. That is safer for partners that do not need silent sign-in.

Post-logout Redirect URIs

Where

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

What

Optional. Empty rows are ignored on save. A filled row must be a valid URL (Post logout URI must be valid.). In the edit form, a list you empty completely is not saved, and the previous addresses stay. Replace them with at least one new address instead.

Why

After signing out through the partner, users should land on the partner’s own page rather than on comrce Hub.

Redirect URIs

Where

The section Redirect URIs, one row per address. Add Redirect URI is below, and a remove button is beside each row. The first row is required.

What

At least one absolute address, each a valid URL with a scheme. Otherwise the form shows Redirect URI must be valid., and an empty row shows Redirect URI is required.. The remove button is disabled while only one row is left. Saving the edit form replaces the whole list.

Why

comrce Hub returns sign-in results only to addresses on this list. A stolen client ID therefore cannot receive them elsewhere.

The new client appears in the list at once. Scopes and grant types are visible only in its edit form.

What this screenshot shows

Screen

API Keys

Highlighted

“Reporting export”: Edit opens the client in its own tab

Also visible

3 API clients; Create tab closed

Purpose

the result of creating a client

Display Name

Where

The second field, Display Name, required. Saved with Save.

What

Plain text, required (Display name is required.). The list sorts clients by this name. The consent page asks the customer Do you want to log in into the display name as their email address.

Why

Customers approve access by name. A name they recognise, such as the partner’s product, makes the difference between an informed approval and a suspicious one.

Do	Don’t
Use the product name customers know: Warehouse dashboard	Use an internal ticket number or the partner’s legal entity
Keep one client per product and environment if the partner needs separate secrets	Reuse one client for two unrelated partners

Other settings on this page

Setting	What it does	Why
Client ID	The first field, greyed out. comrce Hub fills it with a random identifier such as 3f2b8c41-7d6e-4a19-9c52-1e8a7b0d4f63. It can never be changed. An existing ID is refused with Client with this Id already exists. The edit tab carries it as its title.	A random ID cannot be guessed and never collides with an older client. The partner configures it together with the secret.

How the settings combine

Client credentials	Offline access scope	Silent authentication	Result
off	off	off	Users sign in and approve every time. Access ends when the partner’s token expires.
off	on	off	Users sign in once. The partner refreshes access in the background.
off	any	on	Users who approved before are signed in without a page.
on	any	any	In addition, the partner’s server gets tokens of its own, without a user.

Which should I choose?

Start with all three off and add only what the partner names. Client credentials belong to server-side services such as Reporting export. Dashboards that users open daily usually want offline access and silent authentication.

API clients in the API Keys list

The list under API Keys shows every API client, ten per page, sorted by display name.

Column	Shows
Client ID	The generated identifier
Display Name	The name customers see
Redirect URIs	Every redirect URI, shortened
Post Logout URIs	Every post-logout URI, shortened
Edit and Delete	The actions for the row

The list shows no scopes or grant types. Why: the list is for finding a client. The edit form is where you check what it may do.

Editing a client

Select Edit in a row. The client opens in its own tab, titled with its client ID, with a red notice about removing scopes. Saving shows Client updated!, refreshes the list and closes the tab. A failure shows Update failed! above the form. The client ID and the secret never change.

Why: narrowing a client must take effect at once. That is why comrce Hub ends every approval and token of the client in the same step. Customers approve the reduced scopes at their next sign-in.

Removing a scope or client credentials revokes every existing sign-in and token of this client at once.

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 about token revocation

Also visible

Tab title: the client ID; 5 optional scopes selected

Purpose

editing a client and the revocation rule

Deleting a client

Select Delete in a row and confirm. comrce Hub removes the client immediately and shows API client deleted!. The partner can no longer sign anyone in or get tokens with this client ID. A Marketplace partner linked to the client loses that link.

Why: a deleted client cannot be restored. A new client gets a new ID and a new secret that the partner has to configure again.

Deleting is immediate and final. A recreated client gets a new ID and a new secret.

What this screenshot shows

Screen

API Keys

Highlighted

“Delete API Client?”: asks to confirm permanent deletion

Also visible

Buttons Cancel and Delete

Purpose

deleting an API client

Who sees it

Only staff with the Super Admin role. Other staff roles see no sidebar entry. Through a direct link they see only You do not have permission to view this page..

Only staff with the Super Admin role manage API clients. Every other staff role sees this placeholder.

What this screenshot shows

Screen

API Keys

Highlighted

“You do not have permission to view this page.”: none

Also visible

Sidebar without API Keys and Languages

Purpose

the gate that admits only the Super Admin role

API clients in the customer sign-in

Where

Not in the admin console. Customers meet a client when a partner application sends them to comrce Hub to sign in.

What

The customer signs in to comrce Hub and chooses an organization if they have several. The Single Sign-On Request page then shows the client’s display name, their email and the buttons Approve and Deny. Approving sends them back to the client’s redirect URI. comrce Hub remembers the approval per user, client and organization. Approvals and denials appear in the logs.

Why

The customer, not comrce, decides whether a partner may see their data. Your configuration decides what they are asked.

• Nordwind ERP connector with Profile, Email, Stay signed in, Organization and Billing address. The seller’s staff sign in once, and the ERP keeps their invoice address in sync.
• Warehouse dashboard with silent authentication → users who approved once open the dashboard without seeing comrce Hub again.
• Reporting export with client credentials and Write external events. The export service reports completed exports to comrce Hub without any user.

If you remove a scope a partner relies on

Removing a scope signs every customer out of that partner at once. Tell the partner before you save. Their next requests fail until users sign in and approve again.

API clients in the logs

Where

Logs, filtered by event type.

What

Three event types record changes: API client created, API client updated and API client deleted. Each names the Super Admin who acted. Create and update events carry the client ID, display name, URIs, both switches and the effective scopes. The secret is never logged.

Why

When a partner reports that sign-in stopped working, the logs show whether and when someone changed their client.

• A partner says sign-ins fail since Tuesday → filter for API client updated and compare the scopes.
• A client is missing from the list → search the logs for API client deleted and its client ID.
• A security review asks who can sign in where → list every API client created event.

What you need to know

Topic	Fact
Secret shown once	Generated on save, 43 characters long, and shown only in the dialog after creating. Closing the dialog in any way, including Esc or a click outside, loses it.
No secret rotation	The edit form never shows or renews the secret. Create a new client and delete the old one once the partner has switched.
Fixed identifier	Generated by comrce Hub, never editable.
What ends sessions	Removing a scope or client credentials. Adding scopes or changing the name or the URIs ends nothing.
List order and size	Sorted by display name, ten per page, refreshed every minute.
Search	Matches any part of the client ID or display name, ignoring case.
Staff accounts	Cannot sign in to partner applications.
Marketplace partners	A Marketplace partner can be linked to an API client in the partner form. Deleting the client removes the link.

Frequently asked questions

General

Who can create API clients?

Only staff with the Super Admin role. The sidebar entry API Keys is hidden from every other role. A direct link shows them You do not have permission to view this page..

What is the difference between an API client and an API key?

The page is called API Keys, but each entry is an API client. It has a client ID, a secret and redirect URIs. It lets an outside application sign comrce Hub customers in. It is not a key for calling admin functions.

Does an API client cost anything or have a usage limit?

No. comrce Hub has no quota, price or rate setting for API clients under API Keys. A partner can use its client for as many sign-ins as its customers make.

Setup

Can I choose the client ID myself?

No. The create form under API Keys fills Client ID with a random identifier and keeps the field read-only. Give the partner that generated ID together with the secret.

Why is the Save button greyed out?

Save stays disabled until the display name is filled and at least one valid redirect URI is entered. The scope list must also have loaded, and you must have changed something. Check the red messages under the fields.

Which redirect URI format does comrce Hub accept?

Absolute URLs with a scheme, such as https://reports.example.net/auth/callback. An address without https:// shows Redirect URI must be valid.. Users are sent back only to addresses that exactly match an entry.

Can one client serve a partner’s staging and production systems?

Yes. Add one redirect URI per environment with Add Redirect URI in the client’s form. If the partner wants separate secrets per environment, create one client per environment instead.

Do I need to tick Identity (openid)?

No. Identity (openid) is part of every API client and does not appear in the Allowed scopes picker. The note Identity (openid) is always required. under the label says so.

Scopes and grant types

Which scope gives a partner the organization the customer works for?

Organization (comrce.organization) shares the selected organization’s ID and name. Add Billing address for its invoice address. Add Tool permissions for the user’s role and permissions there.

What does Stay signed in do?

Stay signed in (offline_access) lets the partner renew access while the user is away. Removing it from an existing client ends every session and token the client holds, so tell the partner first.

When should I tick Allow client credentials flow?

Only when the partner runs a server-side service that acts without a user, for example one that sends external events. With Allow client credentials flow the service gets tokens for the client itself. Pair it with Write external events for writing events.

Why does a partner’s silent sign-in fail?

Silent sign-in needs Allow silent authentication ticked on the client. The user must also have approved this client before, for the same organization and scopes. A user who never approved, or approved fewer scopes, must go through the visible sign-in once.

Secrets

I closed the secret dialog without copying. Can I see the secret again?

No. comrce Hub shows the client secret exactly once, in the Client Secret dialog after creating the client. Create a new client and give the partner the new ID and secret. Then delete the client whose secret was lost.

How do I rotate a client secret?

The edit form cannot show or renew secrets. Create a second client with the same settings under API Keys. Let the partner switch to the new client ID and secret, then delete the old client.

What does Close at the bottom of the secret dialog do?

Close closes the dialog and the create tab, and it refreshes the API client list. The secret is gone afterwards. Copy it with Copy before you select Close.

Changing and deleting

Does editing a client sign customers out?

Only when you remove a scope or untick Allow client credentials flow. In that case comrce Hub ends every approval and token of the client at once. Changing the display name, adding scopes or changing redirect URIs signs nobody out.

I removed all post-logout URIs but they are still there. Why?

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 them.

Can I undo deleting a client?

No. Deleting under API Keys removes the client immediately. A new client gets a new client ID and secret, and the partner must configure their application with both again.

Customer sign-in

What does the customer see when a partner sends them to comrce Hub?

After signing in and choosing an organization, the customer sees Single Sign-On Request. The page shows the client’s display name and their email. They choose Approve or Deny. Approving returns them to the partner.

Can a comrce staff account sign in to a partner application?

No. Accounts with a staff role are refused at partner sign-in, and the logs record a failed sign-in. Try partner sign-ins with a customer account that belongs to an organization.

Data and privacy

Is the client secret written to the logs?

No. The events API client created and API client updated record the client ID, display name, URIs, switches and scopes. They never record the secret. After creation, only the partner holds it.

What happens to a Marketplace partner linked to a deleted client?

The Marketplace partner stays, and its link to the API client is cleared automatically. If the partner gets a new client, link it in the partner form under Marketplace.

Troubleshooting

Symptom	What to check
The sidebar has no API Keys entry	Your role. Only staff with the Super Admin role see it. Ask a Super Admin under Hub Team.
A direct link shows You do not have permission to view this page.	The same role check. Only staff with the Super Admin role can open API client tabs.
Save stays disabled	Is the name filled in? Is the first redirect URI valid, with https://? Has the scope list loaded? Did you change anything?
Could not load the available scopes. under the scope picker	Select Retry. If it keeps failing, reload the console and check that you are still signed in.
Redirect URI must be valid.	The address lacks a scheme or is not a URL. Enter it in full, such as https://erp.example.com/oauth2/callback.
The secret dialog was closed before copying	The secret cannot be shown again. Create a new client and delete the old one.
The partner reports “redirect URI mismatch”	Compare their callback address character by character with the client’s list in the edit form, including trailing slashes and https.
All users of a partner were signed out	Did someone remove a scope or client credentials? Check API client updated under Logs.
Silent sign-in returns “interaction required”	Tick Allow silent authentication on the client. Then let the user approve once with the visible sign-in.
A colleague tests the partner with a staff account and is refused	Staff accounts cannot use partner sign-in. Use a customer account that belongs to an organization.
Removed post-logout URIs reappear	An emptied list is not saved. Enter a replacement address instead.
Update failed! after saving	Read the field messages. Invalid URIs and unsupported scopes are refused. Save again after correcting them.

Still stuck?

Send the client ID, the time of the failed sign-in and the partner’s error message to the comrce Hub developers. They can look up the client’s settings, its log entries and the sign-in attempts.

Related

• The list of API clients
• Create or edit an API client
• Overview: API client management
• Staff roles and what they can do
• Add a new partner and their offer to the Marketplace