Migrating from the legacy endpoint

Decommission date: 31 January 2027

The legacy endpoint will be decommissioned on 31 January 2027. See Timeline.

If you currently authenticate against the legacy XCIS OAuth endpoint, the following changes apply. These are breaking changes — the new endpoint is not a drop-in replacement.

	Legacy	New
Token endpoint	/oauth/token	/oauth2/token
Grant type	password	client_credentials
Credentials sent	Client ID + secret and an end-user username + password	Client ID + secret only
audience parameter	Not used	Required
token_type in response	bearer (lowercase)	Bearer (capitalised)
Refresh token	Issued for some accounts	Not issued — request a new token instead
Token lifetime	24 hours	8 hours
Scopes	read / write (and STAGE / PRODUCTION)	Capability-based — see Scopes
Credentials	Existing client ID + secret	Same client_id, new client_secret issued — your existing secret will not work

Migration checklist

• Obtain your new client_secret from your XCIS contact (your client_id is unchanged)
• Remove the end-user username and password from your token request
• Add the correct audience value for your environment to your token request (https://stgxcis.mobixone.co.za staging / https://xcis.mobixone.co.za production)
• Update your grant_type to client_credentials
• Update the token endpoint URL
• Check any code that compares token_type against the literal string bearer — it is now Bearer
• Remove any refresh-token logic
• Confirm your token cache handles an 8-hour lifetime
• Test end-to-end in staging before switching production traffic

Watch out for

token_type capitalisation. The legacy server returned lowercase bearer. The new server returns the standard Bearer. If your code compares this value against a hardcoded lowercase string, it will break. Most HTTP clients handle this transparently, but custom integrations sometimes do not — this is the most frequently encountered issue when moving from the legacy endpoint.

No end user. The legacy flow required an end-user username and password alongside your client credentials. The new flow authenticates your system only. There is no user identity in the token.

Timeline

The legacy endpoint is deprecated and will continue to run in parallel with the new endpoint during migration. It will be decommissioned on 31 January 2027. After that date, token requests to the legacy endpoint will fail and legacy tokens will no longer be accepted by the XCIS API.

Migration is not optional. Please plan to complete your migration, including testing in staging, well ahead of this date.