Skip to content
Last updated

User access tokens

A user access token lets your application make requests to the Wise API on behalf of a specific Wise user. Wise issues a user access token once the user authorises the partner application to perform transactions on their behalf.

How you obtain a user access token depends on your integration model:

  • Embedded finance partners: Your end customers each have their own Wise profile and can interact with Wise directly through your application. Because each customer authorises your application individually, you use the authorization code grant to obtain a user access token for each customer. You'll go through this flow once per customer.
    • If you created the user's Wise account, you can use the registration code grant to obtain a user access token for each user.
  • Correspondent and Enterprise partners: Your integration operates through a single Wise profile. There is no end user to redirect through a browser-based authorization flow, so you use the registration code grant to obtain a user access token. You'll typically go through this flow only once during onboarding, then maintain access by refreshing the token.
    • If you can log in to Wise.com, you can also follow the authorization code grant flow.

Both flows return a user access token and a refresh token. Once you have a valid access token, using it in requests is the same regardless of which grant type you used to obtain it.

Regardless of how you obtain your initial tokens, you are responsible for maintaining uninterrupted access by refreshing tokens before they expire. See the Refresh tokens guide for details.

Before you begin

Before you can obtain user access tokens, you must have:

  • Your client ID and client secret (retrieve via Developer Hub).
  • A redirect URL (coordinated during partner onboarding with the Wise implementation team and only required for the authorization code flow).
  • Created a Wise account and user (how this occurs will depend on your integration model and you’ll be guided by your onboarding team).

Obtain a user access token

Select the flow you wish to view in detail:

  • Authorization code flow (for Embedded finance partners)
  • Registration code flow (for Correspondent and Enterprise partners)

Obtaining a user access token via the authorization code flow involves:

  1. Directing the user from your application to the Wise authorisation page.
  2. The user logging in and granting permission.
  3. Wise redirecting the user back to your application with an authorisation code.
  4. Your application exchanging the code for an access token and refresh token.

Redirect to authorisation page

From your application, direct the user to the Wise authorisation page. This is where the user will grant your application permission to perform transactions via the Wise API.

Wise authorisation page URL path:

/oauth/authorize?client_id=<client_id>&redirect_uri=<redirect_uri>&response_type=code&state=<state>

Query parameters:

  • client_id: Your application's client ID.
  • redirect_uri: Your registered redirect URL (must match exactly).
  • response_type: Always code.
  • state: A random string to prevent CSRF attacks. Must be verified on callback.

The user will see a Wise authorisation page where they can log in to the Wise account (if not already logged in), review the permissions your application is requesting, and approve access.

Receive authorisation code

After the user approves access, Wise redirects them back to your redirect_uri with an authorisation code.

The URL will appear in the browser in a format like this:

https://your-app.com/callback?code=<authorization_code>&state=<state>

You’ll exchange the authorization_code value for the token in the next step.

Important!

Verify that the state value matches what you sent in the state parameter when redirecting the user to authorise.

Exchange auth code for tokens

Exchange the auth code returned in the previous step for an access token and refresh token by making a create an OAuth token request with grant_type set to authorization_code.

Example request:

curl -X POST https://api.wise.com/oauth/token \
  -u '<client_id>:<client_secret>' \
  -d 'grant_type=authorization_code' \
  -d 'client_id=<client_id>' \
  -d 'code=<authorization_code>' \
  -d 'redirect_uri=<redirect_uri>'

Required data for this request:

  • client_id and client_secret
  • code is the same authorization code value returned from the previous step.
  • redirect_uri is the redirect URL coordinated with Wise during onboarding.

Example response

The response is the same for both the authorization and registration code flows. It includes both the access_token and refresh_token.

Response
application/json
{
  "access_token": "01234567-89ab-cdef-0123-456789abcdef",
  "token_type": "bearer",
  "refresh_token": "01234567-89ab-cdef-0123-456789abcdef",
  "expires_in": 43199,
  "expires_at": "2025-04-11T03:43:28.148Z",
  "refresh_token_expires_in": 628639555,
  "refresh_token_expires_at": "2045-03-12T13:49:23.552Z",
  "scope": "transfers",
  "created_at": "2020-01-01T12:33:33.12345Z"
}

You can now use the access_token in all profile-level requests and refresh the access token prior to its expiration.

Using the token

Include the access token in the Authorization header when making requests on behalf of the user.

curl -X GET https://api.wise.com/v2/profiles \
  -H 'Authorization: Bearer <USER_ACCESS_TOKEN>'

Managing user access tokens

User access tokens expire after 12 hours. Understanding how token invalidation works is critical to avoiding unexpected 401 errors in production.

Access token invalidation

Only one access token is valid at a time.

When you obtain a new access token (whether via refresh_token, authorization_code, or registration_code) the previously active access token is immediately invalidated. Any requests using the old token will fail with 401 invalid_token.

This means your application must always store and use the most recently issued access token.

This behaviour is the most common cause of unexpected 401 errors for partners in production. It typically occurs when:

  • Multiple backend services independently refresh the token, and one service continues using the old token.
  • A retry mechanism triggers a second refresh before the first response is processed.
  • The new token is not propagated to all services that make API calls.

Recovery paths by integration model

How you recover from token invalidation depends on your integration model:

Embedded finance partners

If the user originally authorised via the OAuth redirect flow:

  1. Attempt to refresh using your stored refresh token.
  2. If the refresh token is also invalid, redirect the user to re-authorise then use the authorization code to obtain new tokens.

Enterprise and Correspondent partners

These integration models use a single partner account and typically go through the authorisation flow only once:

  1. Attempt to refresh using your stored refresh token.
  2. Use your registration code to generate a new token pair. The registration code is your primary recovery mechanism — store it securely!
Using the authorization code flow

Unlike Embedded finance partners, you cannot redirect a user to re-authorise. However, if both your refresh token and registration code are invalid, but you can log in to Wise.com, you may generate an access token via the authorization code flow.

Otherwise, contact your Wise implementation team or Wise Platform support for further assistance.

User access token errors

This section covers the most common errors you may encounter when obtaining or using user access tokens.

Errors when obtaining tokens

Authorization code grant

HTTP statusError Cause
400invalid_grant — "Authorization code expired."The authorisation code has a 10-minute TTL. You must exchange it for tokens within that window.
400invalid_grant — "Authorization code is not valid."The code has already been used. Each authorisation code can only be exchanged once.
400invalid_grant — "Redirect URI mismatch."The redirect_uri in your token request does not match the one used when redirecting the user to authorise. These must be identical, including query parameters.
401invalid_clientYour client_id or client_secret is incorrect, or the Basic Auth header is malformed.
400invalid_request — "Missing grant type"The grant_type parameter is missing from the request body.

Registration code grant

HTTP statusError Cause
401invalid_grant — "Invalid user credentials."The registration code is invalid, or the user has reclaimed their Wise account (for example, by resetting their password).

Refresh token grant

HTTP statusError Cause
400invalid_grantThe refresh token is expired, revoked, or not found. Can also be caused when a profile is moved to a different account.
401invalid_clientYour client_id or client_secret is incorrect. If you recently rotated your client secret, ensure you are using the active secret.

Errors when using tokens

HTTP statusError Cause
401invalid_token — "Invalid token"The access token is expired, was never valid, was revoked, or was replaced by a newer token. Can also be caused by profile ownership change when there is an existing token.
Legacy error format

Some API paths may return {"error": "unauthorized"} instead of {"error": "invalid_token"}. Both indicate the same issue — the token is not valid.

This inconsistency is being addressed as part of an ongoing migration.