CMS Tool API schema
Public API version 1.4.41.
Authentication
Authenticate clients that call the CMS Tool API.
OAuth overview
OAuth 2.0 with PKCE is the recommended authentication method. Send access tokens in the Authorization header as a Bearer token.
The authorization server limits requested scopes to those allowed by the signed-in user's CMS permissions. The user selects the website and approves the requested access.
Environments
Production uses www.cms-tool.net for CMS and OAuth pages, and api.cms-tool.net for the protected API. When testing on dev.cms-tool.net, use that development host consistently for CMS, OAuth, resource, and API URLs.
Discovery
These are OAuth URLs for clients to use with the documented requests. Opening the authorization or token URL without the required parameters or form data will return an error. Read the authorization server metadata before starting authorization.
Authorization server metadata: https://www.cms-tool.net/.well-known/oauth-authorization-server/api/auth
Authorization server metadata (alternative): https://www.cms-tool.net/api/auth/.well-known/oauth-authorization-server
Authorization endpoint: https://www.cms-tool.net/api/auth/authorize
Token endpoint: https://www.cms-tool.net/api/auth/token
API resource: https://api.cms-tool.net
Client registration
A client may use a registered client identifier or an HTTPS Client ID Metadata Document URL as its client_id.
A Client ID Metadata Document must be available without redirects at a stable public HTTPS URL on the normal HTTPS port. Its client_id must equal that URL, and it must declare at least one redirect_uri and token_endpoint_auth_method none.
The metadata document may be served as application/json or text/plain, so a file in a GitHub gist or repository can be used. The body must be a JSON object.
Redirect URIs are compared exactly, except for loopback redirects used by applications on the user's own computer, such as command line tools. For an http redirect to localhost, 127.0.0.1 or [::1] the port is ignored, so a client may register http://localhost/callback and use any port at request time. Scheme, host, path and query must still match.
The consent page names clients that are not registered with CMS Tool as unverified and shows where the user will be returned when the redirect is a loopback address.
Contact CMS Tool support to register private or development clients that cannot publish a Client ID Metadata Document.
Authorization request
Send the user to the authorization endpoint. PKCE using SHA-256 is required.
Parameters
| Name | Type | Example | Notes |
|---|---|---|---|
response_type | text | code | Use code. |
client_id | text | https://client.example/oauth/client.json | Registered client ID or HTTPS client metadata document URL. |
redirect_uri | text | https://client.example/oauth/callback | Must match a redirect URI registered for the client. A loopback redirect may use any port. |
scope | text | products:read products:write | Space-separated scopes requested by the client. The consent page lists them, and the user can approve only these or fewer. MCP clients request the mcp/<tool>:read scopes (and mcp/execute_product_update:write) published in the protected resource metadata; each MCP tool call needs its own scope, or everything:read / everything:write. Scopes that CMS Tool does not define are ignored; if an MCP client requests only unknown scopes, the MCP tool scopes are offered. |
state | text | client-generated-value | Recommended value used by the client to bind the callback to its request. |
code_challenge | text | PKCE-S256-challenge | Base64url SHA-256 challenge derived from the code verifier. |
code_challenge_method | text | S256 | Use S256. |
resource | text | https://api.cms-tool.net | API resource for the requested access token. |
Authorization code exchange
POST form encoded data to the token endpoint. Authorization codes are short lived and can be used once.
Parameters
| Name | Type | Example | Notes |
|---|---|---|---|
grant_type | text | authorization_code | Selects the authorization code grant. |
code | text | returned-authorization-code | Code returned to the redirect URI. |
client_id | text | https://client.example/oauth/client.json | The same client ID used for authorization. |
redirect_uri | text | https://client.example/oauth/callback | The same redirect URI used for authorization. |
code_verifier | text | original-PKCE-verifier | Original verifier used to create the S256 challenge. |
Refresh tokens
POST a refresh token to the token endpoint to obtain a new access token. Access tokens expire after one hour.
Refresh tokens rotate after every successful refresh and have a rolling 90-day lifetime. Replace the stored refresh token with the new value returned by each refresh.
Parameters
| Name | Type | Example | Notes |
|---|---|---|---|
grant_type | text | refresh_token | Selects the refresh token grant. |
refresh_token | text | issued-refresh-token | Refresh token issued by the token endpoint. |
client_id | text | https://client.example/oauth/client.json | Client that received the refresh token. |
scope | text | products:read | Optional subset of the originally granted scopes. |
Calling the API
Send Authorization: Bearer access-token on each request. Read operations use endpoint:read scopes and write operations use endpoint:write scopes.
Broad access can be requested with everything:read and everything:write. Request only the access the client needs; the user may approve fewer scopes.
The OAuth connection selects the authorised website. A client must not attempt to change the website represented by its access token.
Credential safety and revocation
Store access tokens, refresh tokens, API IDs, and API keys as credentials. Do not place them in public source code, browser URLs, logs, or client-side code where another user can copy them.
A website owner or administrator can disconnect an OAuth connection. Disconnection invalidates the connection before its normal token expiry when required.
Legacy API credentials
Existing integrations may continue to provide apiID and apiKey as request headers, request parameters, or multipart form parameters. New integrations should use OAuth.
Legacy credentials can provide broad website access or be constrained by the current permissions of an associated CMS user. They must be stored securely.
/api/auth/authorize
Start or approve an OAuth authorization request.
/api/auth/token
Exchange an authorization code or refresh token.
/api/auth/.well-known/oauth-authorization-server
Read OAuth authorization server metadata.
Machine-readable documentation
This documentation is also available as JSON or Markdown at the same URL. Request JSON with Accept: application/json or Markdown with Accept: text/markdown.