Authentication

Everything about getting, using and troubleshooting an access token. If you just want a working call, start with Quick Start and come back here when something breaks.

Every request to the Standard Interface API carries an OAuth 2.0 access token issued by the token endpoint. This is the only supported way to authenticate a new integration — build against it and nothing else.

The flow

The API uses the OAuth 2.0 client credentials grant. There is no user involved and no login screen — your application authenticates as itself.

An administrator registers your application

Your RBS administrator registers it against one customer, one product, and an explicit set of read and write permissions.

You exchange credentials for a token

Your application sends its Client ID and Secret to the token endpoint and receives a short-lived access token.

You send the token to Standard Interface

In the Authorization header, as Bearer {access_token}.

Standard Interface verifies and enforces

It verifies the token offline against the token endpoint's public keys, then enforces the permissions carried inside it.

INFO

client_credentials is the only supported grant type. There is no authorization-code flow, no delegated or on-behalf-of-a-user access, no mutual TLS, and no private-key-JWT client authentication. If your risk assessment requires stronger client authentication, raise it with WinCloud Support Team before you integrate.

Requesting a token

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "reservations:read rates:read inventory:read"
}

CAUTION

Send the credentials as JSON, as shown above, or let your HTTP library encode the form for you. Client secrets can contain characters like &, =, % and #. A hand-built form body works most of the time, then fails with INVALID_CLIENT_CREDENTIALS the first time a new secret happens to contain one of them — which looks like a wrong secret and is very hard to diagnose.

A JSON body, or your library's form encoder, or curl --data-urlencode.

A form body built by string concatenation.

The audience parameter

audience names the interface the token is for. For the Standard Interface API it is always:

wincloud

DANGER

Send it on every token request. If you omit it, the token is issued without an aud claim, and Standard Interface will reject it when you try to use it. The token request itself succeeds, so this failure surfaces later and looks unrelated.

An audience that is not a configured interface returns 401 AUDIENCE_NOT_REGISTERED. This is almost always a typo.

An audience that is configured but belongs to another product returns 401 AUDIENCE_NOT_PERMITTED. Contact WinCloud Support Team if you need access to it.

Each set of credentials is tied to one customer and one product, so one set of credentials can never span more than one interface.

Permissions

A permission is <feature>:<operation>, where the operation is read or write. Granting write also allows read.

Feature	Read	Write
Reservations	`reservations:read`	`reservations:write`
Rates	`rates:read`	`rates:write`
Inventory	`inventory:read`	`inventory:write`

Your token's scope field lists the complete set granted to your application. Read it at runtime rather than assuming — it tells you exactly what you can do.

WARNING

A request whose token lacks the required permission is rejected with 403 Forbidden. That is different from 401 Unauthorized, which means the token itself is missing, expired or invalid. Do not refresh your token in response to a 403 — a new token has the same permissions and will fail the same way.

Permission changes apply to your next token. If an administrator adds or removes a permission, the token you already hold keeps its existing permissions until it expires, so a change can take up to 15 minutes to take effect.

Features are configuration rather than code, so this list can grow without a software release. Confirm the current set for your environment with WinCloud Support Team before relying on it.

Token lifetime and reuse

Access tokens last 15 minutes. Read expires_in from the token response rather than hardcoding a lifetime — it is an environment setting and can change.

The pattern to implement:

Keep the token in memory. One token per process, reused for its full life.

Request a new token about 60 seconds before it expires.

If an API call returns 401, get one fresh token and retry that call once. If it still fails, stop retrying and check the audience, permissions and credentials.

DANGER

Do not request a token per API call. The token endpoint is rate limited and this will trip it. Reusing one token for its full life means roughly four token requests an hour.

There is no refresh token. The client credentials grant does not use one. To renew access, call the token endpoint again with the same Client ID and Secret.

CAUTION

A token cannot be cancelled once issued. If your application is revoked or its permissions change, the token you already hold keeps working until it expires — up to 15 minutes. The same is true in reverse: getting a new token does not invalidate the old one, and more than one of your tokens can be valid at the same time. That is normal OAuth behaviour, not a fault.

Client secrets do not expire. If a secret is lost, or you believe it has leaked, ask your RBS administrator to rotate it immediately. A secret cannot be looked up after it is issued.

Keeping your credentials safe

Store the client secret in a secret manager. Never in source code, a committed config file, a CI variable printed to build logs, or application logs.

The Client ID is safe to log. The Client Secret is not.

Never expose credentials in a browser or mobile client. The client credentials grant is for server-to-server use. Anything shipped to a user's device can be read by that user.

Use separate credentials for separate integrations, so one can be revoked without breaking the other.

DANGER

If a secret leaks, treat it as compromised immediately. Ask your administrator to rotate it, then purge it from wherever it was shared. Any token already issued keeps working until it expires, so assume up to 15 more minutes of exposure.

Token endpoint errors

Every token failure returns the same object — one error_code naming the exact condition, plus a human-readable description.

{
  "error_code": "CLIENT_REVOKED",
  "error_description": "This client is inactive or has been revoked",
  "error_uri": null
}

CAUTION

Branch on error_code, never on error_description. The wording may change; the codes are the contract.

This is not the standard response envelope used by the rest of the API — the token endpoint follows the OAuth error format instead. See General for the envelope used by Standard Interface endpoints.

HTTP	`error_code`	What it means	What to do
400	`UNSUPPORTED_GRANT_TYPE`	`grant_type` is not `client_credentials`	Send `"grant_type": "client_credentials"`. It is the only grant this endpoint supports
401	`INVALID_CLIENT_CREDENTIALS`	Unknown client ID, or wrong client secret. The two are deliberately indistinguishable	Re-copy the secret and send it as JSON. If it is lost, ask your administrator to rotate it — it cannot be looked up
401	`CLIENT_REVOKED`	The application is inactive or has been revoked	You cannot fix this yourself. Contact WinCloud Support Team — an administrator must reinstate the application
401	`CLIENT_EXPIRED`	The application is past its expiry date	You cannot fix this yourself. Contact WinCloud Support Team to have the expiry extended
401	`SCOPE_EXCEEDS_GRANT`	The requested `scope` exceeds what you were granted	Drop `scope` from the request to receive your full granted set, or ask your administrator for the extra permission
401	`AUDIENCE_NOT_REGISTERED`	The `audience` you sent is not a configured interface	Usually a typo. For this interface the value is `wincloud`
401	`AUDIENCE_NOT_PERMITTED`	The `audience` is a real interface, but belongs to another product	Your credentials are not for that interface. Send your own `audience`, or contact WinCloud Support Team if you need access
422	`INVALID_REQUEST_BODY`	A required field is missing, oversized, or the body is not valid JSON	Check the request body against the example above
429	`RATE_LIMITED`	Too many token requests	Back off, then reuse the token you already hold instead of requesting another. No `Retry-After` header is sent
503	`SIGNING_NOT_CONFIGURED`	Token signing is not configured in that environment	Not fixable on your side. Report it to WinCloud Support Team with the environment name and the time

The flow#

Requesting a token#

The audience parameter#

Permissions#

Token lifetime and reuse#

Keeping your credentials safe#

Token endpoint errors#

The flow

Requesting a token

The audience parameter

Permissions

Token lifetime and reuse

Keeping your credentials safe

Token endpoint errors