Skip to main content

Migration Flow

The migration flow is a one-time process that is used to migrate a Service User from the PermissionId based flow to the OAuth 2.0-based flow.

bLink‑issued Tokens vs. Service Provider Tokens (CaaS)

In the CaaS model, two different token layers exist:

  • Service Provider tokens
    These are the actual OAuth 2.0 access and refresh tokens issued by the Service Provider.
    They remain internal to bLink and are never exposed to the Service User.

  • bLink‑issued tokens
    bLink returns its own access and refresh tokens to the Service User.
    When the SU calls bLink with these tokens, bLink exchanges them for the corresponding SP tokens and forwards the request to the SP.

During migration, bLink uses the internal SP refresh token to perform a refresh and obtain updated SP tokens including the grant_id.
The Service User only interacts with the bLink‑issued tokens, not with Service Provider tokens.

  1. Service User calls migration endpoint
    • The Service User sends POST /permissions/permissionId/tokens/exchange to convert a PermissionId into standard OAuth 2.0 tokens.
  2. bLink validates the PermissionID and Service User authorization
    • bLink checks whether the PermissionId exists, is active, and belongs to the requesting Service User.
    • bLink internally exchanges the permission
  3. To obtain the grant_id, bLink performs a refresh call to the Service Provider using the internal refresh token.
  4. The Service Provider returns the updated token including the grant_id.
  5. bLink issues a new OAuth 2.0 token
  6. bLink returns a new OAuth 2.0 token response
  7. The Service User persists the access_token + refresh_token and stops using the PermissionId
    • From this point on the Service User is responsible for the refresh flow.
    • The Permission will remain valid for a short grace period or until the first successful API call with the new access_token.
    • The Service User proceeds with an API call with the new access_token. The new access_token is exchanged for the service provider tokens and relayed to the Service Provider.
  8. The Service Provider returns the API response to the Service User

Examples - Migration Flow​

Token exchange request

POST "permissions/123e4567-e89b-12d3-a456-426614174000/tokens/exchange"
-H "X-Correlation-ID: 7a7d4a34-0d9f-4e4b-9e50-2b28f2142e1b"
-H "X-CorAPI-Target-ID: IIDP99999"
-H "X-PSU-User-Agent: AUTO"
-H "User-Agent: MySU/1.0"
-H "Accept: application/json"

Successful response (200)

{ 
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.migrated123", 
"token_type": "Bearer", 
"expires_in": 3600, 
"refresh_token": "bWlncmF0ZWQtcmVmcmVzaC10b2tlbg", 
"grant_id": "3f5dd8a4-7e3a-47af-92e8-2e2bc5bcd011", 
"scope": "urn:blink:xs2a:ais urn:blink:xs2a:pss:write" 
}

Error response (401)

{
  "error" : "invalid_token",
  "error_description" : "permission is invalid, expired, or does not belong to the requesting client"
}
Last updated on