OAuth Token Format Migration¶

This guide explains the new opaque token format introduced in SDK version 1.2.0.

What's Changing¶

Starting January 2026, Contio OAuth tokens use a new opaque format:

Why We're Making This Change¶

• Improved Security - Tokens no longer expose internal claims or implementation details
• Future Flexibility - Versioned format enables seamless upgrades
• Privacy - No sensitive information visible in token strings

What You Need to Do¶

If You Decode Access Tokens as JWTs¶

Action Required: Use the /oauth2/introspect endpoint instead.

Before (will stop working):

// ❌ Don't do this - access tokens are no longer JWTs
const payload = jwt.decode(accessToken);
const userId = payload.sub;
const scopes = payload.scope;

After (recommended approach):

// ✅ Use token introspection
const tokenInfo = await oauth.introspectToken(accessToken);
const userId = tokenInfo.sub;
const scopes = tokenInfo.scope;

If You Parse Token Strings¶

Action Required: Stop parsing tokens and use introspection.

// ❌ Don't do this
if (token.startsWith('eyJ')) {
  // handle as JWT
}

// ✅ Do this instead
const tokenInfo = await oauth.introspectToken(token);
if (tokenInfo.active) {
  // token is valid
}

If You Use Our SDK¶

No action required. The SDK handles tokens as opaque strings and automatically uses introspection when needed.

If You Verify ID Token Signatures¶

No action required. ID tokens remain JWTs and can be verified using the JWKS endpoint at /.well-known/jwks.json.

Deprecation Timeline¶

Detecting Legacy Tokens¶

If you're using legacy JWT tokens, API responses will include deprecation headers:

Deprecation: true
Sunset: Sat, 08 Jul 2026 00:00:00 GMT
Link: <https://docs.contio.ai/partner-api/guides/token-migration/>; rel="deprecation"
X-Contio-Token-Deprecated: true

Introspection Endpoint¶

The introspection endpoint is the authoritative source for token metadata:

curl -X POST https://api.contio.ai/oauth2/introspect \
  -H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=cto_at_v1_..."

Response:

{
  "active": true,
  "sub": "user-uuid",
  "client_id": "your-client-id",
  "scope": "openid profile meetings:read",
  "exp": 1704672000,
  "iat": 1704585600
}

Token Format Details¶

New tokens follow this format:

Example access token:

cto_at_v1_7f3d8a2b1c4e5f6a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a

FAQ¶

Can I still use existing tokens?¶

Yes, existing JWT-format tokens will continue to work until July 8, 2026. However, you should migrate to handle opaque tokens as soon as possible.

How do I know which format my tokens use?¶

• New format: Starts with cto_at_v1_ or cto_rt_v1_
• Legacy format: Starts with eyJ (JWT) or other patterns

Will token lifetimes change?¶

No. Token lifetimes remain the same: - Access tokens: 24 hours - Refresh tokens: 30 days

Do I need to re-authenticate users?¶

No. Existing user connections will continue to work. New tokens issued after the change will use the opaque format.

Need Help?¶

Contact partner-support@contio.ai if you have questions about migrating to the new token format.