API Website World

Applications need a client ID before they can start a CMS-Tool OAuth authorization request.

CMS-Tool supports two ways to identify an OAuth client:

Client ID Metadata Documents (CIMD) — recommended for applications that can publish a stable public HTTPS metadata document.
Manual registration - Contact Support — suitable for applications that cannot publish a CIMD document, including many development or private integrations. Contact support with information about your application, and your redirect URL.

OAuth Authorization Server

/api/auth

Authorization endpoint:

/api/auth/authorize

Token endpoint:

/api/auth/token

Authorization-server metadata:

/api/auth/.well-known/oauth-authorization-server

CMS-Tool advertises:

"client_id_metadata_document_supported": true

Option 1 — Client ID Metadata Document (Recommended)

If your application controls a stable public HTTPS website, publish a small JSON document describing the OAuth client. The HTTPS URL of that document becomes the application's client_id.

For example, publish:

https://example.com/oauth/client-metadata.json

with content similar to:

{
  "client_id": "https://example.com/oauth/client-metadata.json",
  "client_name": "Example CMS-Tool Integration",
  "client_uri": "https://example.com/",
  "redirect_uris": [
    "https://example.com/oauth/callback"
  ],
  "token_endpoint_auth_method": "none"
}

The client_id inside the document must exactly equal the metadata-document URL.

CIMD URL Requirements

The URL must use HTTPS.
The URL must be publicly reachable from the CMS-Tool authorization server.
The URL must use the normal HTTPS port.
The URL must contain a non-root path, such as /oauth/client-metadata.json.
The URL must not contain a username, password, query string or fragment.
The URL should be stable and should not change between authorization requests.
The server must return a JSON document without redirecting to another URL.

Redirect URIs

The document must contain at least one permitted redirect URI:

"redirect_uris": [
  "https://example.com/oauth/callback"
]

You may list more than one redirect URI where required:

"redirect_uris": [
  "https://example.com/oauth/callback",
  "https://app.example.com/oauth/callback"
]

CMS-Tool uses exact redirect-URI matching. The redirect_uri used in the authorization request must exactly match one of the values in the metadata document.

Using the CIMD URL

Use the metadata-document URL directly as the client ID:

client_id=https://example.com/oauth/client-metadata.json

For example:

GET /api/auth/authorize
    ?client_id=https%3A%2F%2Fexample.com%2Foauth%2Fclient-metadata.json
    &redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
    &response_type=code
    &code_challenge=YOUR_PKCE_CODE_CHALLENGE
    &code_challenge_method=S256
    &resource=https%3A%2F%2Fapi.cms-tool.net
    &state=YOUR_STATE

No client secret is required. CMS-Tool uses Authorization Code + PKCE using S256.

Option 2 — Register an Application with CMS-Tool Support

If your application cannot publish a stable public CIMD document, contact CMS-Tool support and ask for the application to be registered.

Provide:

Application name.
A short description of the integration.
Developer or organisation name.
An application/support website where available.
Every redirect URI the application needs to use.

For example:

Application name: Example Inventory Integration
Application website: https://example.com/
Redirect URI: https://example.com/oauth/callback

CMS-Tool support will register the application and provide a client ID. Use that client ID exactly as supplied.

If a registered application later needs another redirect URI, contact support before using it. Unregistered redirect URIs are rejected.

Which Method Should I Use?

Use CIMD when your application has a stable public HTTPS site and can host a small metadata document.

Use manual registration when the integration is private, in development, uses a local callback, cannot publish public metadata, or requires CMS-Tool support to manage the client identity.

Security Notes

Do not use another application's client ID.
Do not put access tokens or refresh tokens in the CIMD document.
Do not publish a client secret. CMS-Tool's current public-client flow uses PKCE instead.
Keep redirect URIs as narrow and specific as possible.
Use the same client ID when exchanging an authorization code and when refreshing a token.

OAuth Client ID and Application Registration