API Website World

OAuth 2.0 is recommended for new integrations. It allows a CMS-Tool user to authorise an application for a selected website without giving that application the user's CMS password or permanent API key. Access can be limited using scopes, tokens are short-lived, and the OAuth connection can be disconnected by the website owner or administrator.

Existing integrations using API ID and API Key authentication can continue to use that method. Legacy authentication is not being removed.

OAuth 2.0 — Recommended for New Integrations

OAuth is suitable for third-party applications, automated services, integrations and AI agents that need access to a customer's CMS-Tool website.

The OAuth authorization server is provided through:

https://www.cms-tool.net/api/auth

OAuth Endpoints

Authorization endpoint:

https://www.cms-tool.net/api/auth/authorize

Token endpoint:

https://www.cms-tool.net/api/auth/token

Authorization server metadata:

https://www.cms-tool.net/api/auth/.well-known/oauth-authorization-server

The protected API resource is:

https://api.cms-tool.net

How OAuth Authorization Works

The application sends the user's browser to the CMS-Tool authorization endpoint.
If the user already has an active CMS-Tool session, CMS-Tool can use that session rather than requiring another login.
The user selects the website the application may access.
The user reviews and approves the requested permissions (scopes).
CMS-Tool redirects the browser to the application's registered redirect URI with a short-lived, one-time authorization code.
The application exchanges that authorization code for an access token and refresh token.
The application sends the access token with API requests.
When the access token expires, the application uses the refresh token to obtain a new access token without asking the user to authorise the connection again.

OAuth connections can be revoked by the website owner or administrator. Revocation invalidates the connection even if an access token has not yet reached its normal expiry time.

Authorization Code Flow with PKCE

CMS-Tool uses the OAuth Authorization Code flow with PKCE using S256.

A typical authorization request includes:

client_id: The application's OAuth client identifier.
redirect_uri: The callback URI for the application. It must be permitted for the client and is compared exactly.
response_type: Must be code.
code_challenge: The PKCE challenge generated from the application's code verifier.
code_challenge_method: Must be S256.
state: Recommended. A value generated by the application and checked when the user returns to the application.
resource: Use https://api.cms-tool.net.
scope: The permissions requested by the application. Scopes are separated by spaces.

Example authorization request:

GET /api/auth/authorize
    ?client_id=YOUR_CLIENT_ID
    &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
    &scope=everything%3Aread%20everything%3Awrite
    &state=YOUR_STATE

After approval, CMS-Tool redirects to the registered callback URI:

https://example.com/oauth/callback?code=AUTHORIZATION_CODE&state=YOUR_STATE

The authorization code is short-lived and can only be used once.

Exchange the Authorization Code for Tokens

POST the following form values to:

/api/auth/token

grant_type=authorization_code
client_id=YOUR_CLIENT_ID
code=AUTHORIZATION_CODE
redirect_uri=YOUR_REGISTERED_REDIRECT_URI
code_verifier=YOUR_PKCE_CODE_VERIFIER

A successful response is similar to:

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN",
  "refresh_token_expires_in": 7776000,
  "scope": "everything:read everything:write"
}

Access and refresh tokens are credentials and must be stored securely. Do not expose them in public source code, browser URLs, logs or client-side code where they can be copied by another user.

Using an OAuth Access Token

Send the access token using the standard HTTP Authorization header:

Authorization: Bearer ACCESS_TOKEN

For example:

GET https://api.cms-tool.net/api/product
Authorization: Bearer ACCESS_TOKEN

The OAuth connection determines the authorised website and permissions. Applications should not attempt to change the website represented by the access token.

Refreshing an Access Token

Access tokens currently expire after one hour. Use the refresh token to obtain a replacement without asking the user to approve the application again.

POST to:

/api/auth/token

with:

grant_type=refresh_token
client_id=YOUR_CLIENT_ID
refresh_token=YOUR_CURRENT_REFRESH_TOKEN

A successful refresh returns a new access token and a new refresh token:

{
  "access_token": "NEW_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "NEW_REFRESH_TOKEN",
  "refresh_token_expires_in": 7776000,
  "scope": "everything:read everything:write"
}

CMS-Tool uses refresh-token rotation. After a refresh succeeds, the refresh token used for that request is no longer valid. The application must immediately replace its stored refresh token with the new refresh token returned in the response.

Refresh tokens use a rolling 90-day lifetime. Each successful refresh rotates the token and extends the active OAuth connection for another 90 days. If the connection is revoked or allowed to expire, the user must authorise a new connection.

OAuth Scopes

Scopes determine what the application can do.

Broad scopes include:

everything:read: Allows read operations across the API.
everything:write: Allows write operations across the API and also permits the corresponding read operations.

Applications can request more restricted endpoint scopes where appropriate, for example:

product:read
product:write
order:read
order:write

Applications should request only the permissions they reasonably require. The user may approve fewer permissions than requested.

Obtaining a Client ID

Before starting an OAuth authorization request, an application needs a client ID and at least one permitted redirect URI. See the separate OAuth Client ID and Application Registration developer guide.

oAuth Instructions