{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/developer/auth-and-security/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["sub-header","example-box"]},"type":"markdown"},"seo":{"title":"Client credentials token format migration","siteUrl":"https://docs.wise.com","projectTitle":"Wise Platform","description":"Client Credentials Token Format Migration guide: Moving from UUID tokens to JWT tokens","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"client-credentials-token-format-migration","__idx":0},"children":["Client credentials token format migration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"span","attributes":{"class":"sub-header"},"children":["Learn about the Wise migration from UUID tokens to JWT tokens."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API integrations receive an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]}," when using the Client Credentials OAuth flow. Wise is migrating these access tokens from opaque UUID tokens to JWT tokens (encrypted JWT/JWE)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide explains what's changing, who is impacted and what you need to do to remain compatible."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"timelines","__idx":1},"children":["Timelines"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Transition period from ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["mid June 2026"]}," (Sandbox): JWT token formats will be returned"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Transition period from ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["end July 2026"]}," (Production): UUID and JWT token formats may both be returned"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deadline to migrate: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["7 January 2027"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After the deadline: only JWT tokens will be issued, and UUID tokens will no longer be supported."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"whats-changing","__idx":2},"children":["What's changing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Only the format of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]}," value is changing. The way you use it does not change and you can continue sending tokens as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer <access_token>"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"old-format-uuid-opaque","__idx":3},"children":["Old format: UUID (opaque)"]},{"$$mdtype":"Tag","name":"ExampleBox","attributes":{"title":"Example Response with UUID token (200 - OK)","type":"code"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"access_token\": \"ca44a17e-9b28-4fb7-bcf7-9ba09340c26f\",\n \"token_type\": \"bearer\",\n \"expires_in\": 43199,\n \"scope\": \"transfers\",\n \"expires_at\": \"2026-05-06T00:57:28.213Z\"\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"new-format-jwtjwe","__idx":4},"children":["New format: JWT/JWE"]},{"$$mdtype":"Tag","name":"ExampleBox","attributes":{"title":"Example Response with JWT (200 - OK)","type":"code"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"access_token\": \"eyJhbGciOiJSUzI1NiIsImVuYyI6IkEyNTZHQ00iLCJ0eXAiOiJKV1QifQ.eyJzdWIiOiIzIiwiaXNzIjo...\",\n \"token_type\": \"bearer\",\n \"expires_in\": 43199,\n \"scope\": \"transfers\",\n \"expires_at\": \"2026-05-06T00:57:28.213Z\"\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JWT token characteristics"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Typically 500-800+ characters (length varies)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Dot-separated sections (JWE commonly has 5 parts)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Should be treated as an opaque string (do not parse or enforce UUID rules)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"who-is-impacted","__idx":5},"children":["Who is impacted"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You are impacted if your integration does any of the following with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Stores tokens in a UUID-typed database column"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Validates tokens with UUID regex checks or UUID parsers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Assumes tokens are always 36 characters and include hyphens"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Performs UUID-specific conversions (for example, converting to a binary UUID type)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you store the token as a string and only use it as a bearer token in the Authorization header, you are likely unaffected."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-you-need-to-do","__idx":6},"children":["What you need to do"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-1-update-database-storage","__idx":7},"children":["Step 1: Update database storage"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Store access tokens in a string field that can hold long values."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Recommended"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["TEXT, or a sufficiently large VARCHAR (for example, VARCHAR(2048) or larger)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Avoid"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["UUID column types for access tokens"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Length limits that could truncate tokens"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-2-update-application-code","__idx":8},"children":["Step 2: Update application code"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Handle ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]}," as an opaque string."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Do"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store and pass the token as a string"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use minimal validation (for example: non-empty string)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Don't"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Parse/cast to UUID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Apply UUID regex validation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enforce fixed length (36 chars)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"step-3-test-in-sandbox","__idx":9},"children":["Step 3: Test in sandbox"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before deploying to production:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Request Client Credentials tokens in sandbox"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm tokens can be stored without truncation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm API calls succeed using: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer <access_token>"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm no UUID validation/parsing paths reject the new format"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"frequently-asked-questions","__idx":10},"children":["Frequently asked questions"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"do-i-need-to-decode-the-jwt","__idx":11},"children":["Do I need to decode the JWT?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No, treat the token as an opaque bearer token. Your integration should not depend on decoding token contents."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"does-the-oauth-flow-change","__idx":12},"children":["Does the OAuth flow change?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No, only the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]}," format changes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Contact your Customer Success Manager if you have questions about operational queries. Otherwise, reach out to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:api@wise.com"},"children":["api@wise.com"]}," for technical queries."]}]},"headings":[{"value":"Client credentials token format migration","id":"client-credentials-token-format-migration","depth":1},{"value":"Timelines","id":"timelines","depth":2},{"value":"What's changing","id":"whats-changing","depth":2},{"value":"Old format: UUID (opaque)","id":"old-format-uuid-opaque","depth":3},{"value":"New format: JWT/JWE","id":"new-format-jwtjwe","depth":3},{"value":"Who is impacted","id":"who-is-impacted","depth":2},{"value":"What you need to do","id":"what-you-need-to-do","depth":2},{"value":"Step 1: Update database storage","id":"step-1-update-database-storage","depth":3},{"value":"Step 2: Update application code","id":"step-2-update-application-code","depth":3},{"value":"Step 3: Test in sandbox","id":"step-3-test-in-sandbox","depth":3},{"value":"Frequently asked questions","id":"frequently-asked-questions","depth":2},{"value":"Do I need to decode the JWT?","id":"do-i-need-to-decode-the-jwt","depth":3},{"value":"Does the OAuth flow change?","id":"does-the-oauth-flow-change","depth":3}],"frontmatter":{"seo":{"description":"Client Credentials Token Format Migration guide: Moving from UUID tokens to JWT tokens","title":"Client credentials token format migration"}},"lastModified":"2026-06-05T07:18:15.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/developer/auth-and-security/client-credentials-token-migration","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}