CMS Tool API schema
Public API version 1.4.10.
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
OAuth clients should read the authorization server metadata before starting authorization.
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.
Redirect URIs are compared exactly. 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. |
scope | text | products:read products:write | Space-separated scopes requested by the client. |
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 and 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.