Vitu Classic to New API Migration Guide

What's Changing & When

API functionality stays the same. Only how you authenticate and which domain you call changes.

In total, four settings change, in both stage and production. Every endpoint path, request payload, and response shape stays exactly as it is today.

Changes
  • Auth URL
  • Client credentials
  • Scope
  • API domain
Stays the Same
  • Every endpoint path
  • Request payloads
  • Response shapes
All customers migrated by December 31, 2026

Both the Classic API and the new API are available in the meantime, so you can migrate stage, verify, and schedule production on your own release calendar.

Update Settings

Start from the setup process in the Quick Start, then update the four values below. Do this in stage first, confirm, then repeat the same swaps in production.

SettingFrom (Classic)To (new API)
Auth URLhttps://vitu-stage.us.auth0.com/oauth/token?audience=https%3A%2F%2Fvitu.com%2Fnational-public-apihttps://auth.stage.vitu.com/realms/api/protocol/openid-connect/token
API domainhttps://proxy-stage-developer.vitu.comhttps://api-stage.vitu.com
Client credentialsExisting stage clientId and secretNew stage clientId and secret, requested in the developer portal
ScopeNot used — access was scoped by the audience parameteroneapi:access

Note the shape of the new auth URL: the audience query parameter is gone. Token requests are now standard OAuth 2.0 client-credentials calls against a Keycloak endpoint, and they carry the scope oneapi:access in the request body.

Migration Checklist

Request New Client Credentials

On the developer portal's Key Management page, request credentials for stage and for production. These are new values; your Classic clientId and secret will not work against the new auth URL.

Update the Auth URL and Scope in your Configuration

Point your token request at the new endpoint, drop the audience parameter, and send scope=oneapi:access.

Update the Base Domain

Swap the domain your client points at. Everything after the domain — paths, query strings, bodies, headers — stays exactly as it is today.

Verify in Stage

Request a token, then run one read call and one write call you already rely on. Compare the responses with what Classic returns.

Promote to Production

Apply the same four changes with your production credentials and domain, and retire the Classic values from your configuration.

Requesting a Token

Stage values shown. For production, use https://auth.secure.vitu.com/realms/api/protocol/openid-connect/token. The response is a standard bearer token; send it as Authorization: Bearer <access_token> exactly as you do today.

curl -X POST https://auth.stage.vitu.com/realms/api/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$VITU_CLIENT_ID" \
  -d "client_secret=$VITU_CLIENT_SECRET" \
  -d "scope=oneapi:access"

Failures

Getting Help

Credentials, portal access, and environment questions all start in the developer portal. If a call behaves differently on the new domain than it does on Classic, contact your Vitu account manager with the request, the response, and the environment, and we will trace it.