Section 8: Exchanging Authorization Code for Tokens

After the user grants consent and you receive the authorization code in your callback, the next step is exchanging that code for access and ID tokens. The access token allows you to retrieve the user's financial data, and the ID token contains verified user identity information.

Overview

This section covers:

1. Making the token exchange request to the OFP's token endpoint
2. Understanding the response including access token, ID token, and authorization details
3. Validating the ID token signature using the OFP's public keys
4. Handling token lifetime and refresh

Prerequisites

Before making a token exchange request, ensure you have:

Making the Request

Endpoint

POST {{token_endpoint}}

Transport Security

mTLS required - Use your transport certificate and key

Headers

Content-Type: application/x-www-form-urlencoded
x-fapi-interaction-id: 550e8400-e29b-41d4-a716-446655440000

Request Body (Form-Encoded)

Base parameters (always required):

grant_type=authorization_code
&client_id={{CLIENT_ID}}
&code={{AUTHORIZATION_CODE}}
&redirect_uri={{YOUR_REDIRECT_URI}}
&code_verifier={{PKCE_CODE_VERIFIER}}

Plus client authentication parameters:

• If using private_key_jwt: See Method 1: private_key_jwt for how to add client_assertion_type and client_assertion
• If using tls_client_auth: No additional parameters needed; mTLS connection proves identity

Example cURL Request (private_key_jwt)

curl -X POST "{{token_endpoint}}" \
  --cert /path/to/transport-certificate.pem \
  --key /path/to/transport-key.pem \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "x-fapi-interaction-id: 550e8400-e29b-41d4-a716-446655440000" \
  -d "grant_type=authorization_code" \
  -d "client_id={{CLIENT_ID}}" \
  -d "code={{AUTHORIZATION_CODE}}" \
  -d "redirect_uri={{YOUR_REDIRECT_URI}}" \
  -d "code_verifier={{PKCE_CODE_VERIFIER}}" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion={{SIGNED_CLIENT_ASSERTION_JWT}}"

Example cURL Request (tls_client_auth)

curl -X POST "{{token_endpoint}}" \
  --cert /path/to/transport-certificate.pem \
  --key /path/to/transport-key.pem \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "x-fapi-interaction-id: 550e8400-e29b-41d4-a716-446655440000" \
  -d "grant_type=authorization_code" \
  -d "client_id={{CLIENT_ID}}" \
  -d "code={{AUTHORIZATION_CODE}}" \
  -d "redirect_uri={{YOUR_REDIRECT_URI}}" \
  -d "code_verifier={{PKCE_CODE_VERIFIER}}"

Response

200 - Success Response

{
  "access_token": "550e8400-e29b-41d4-a716-446655440000",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid accounts",
  "id_token": "eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImtleTEifQ.eyJpc3MiOiJodHRwczovL2F1dGgxLnNhbmRib3gubXlhLm96b25lYXBpLmlvIiwic3ViIjoiZGVkZmJjM2MtMTAzNy00YzU4LWFjZDAtMDM2YzAxNzE1ZjBmIiwiYXVkIjoiNTUwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAwIiwiaWF0IjoxNjczNjQ3ODAwLCJleHAiOjE2NzM2NTE0MDB9.signature...",
  "refresh_token": "550e8400-e29b-41d4-a716-446655440001",
  "authorization_details": [
    {
      "type": "urn:openfinance-ml:account-access-consent:v1.2",
      "consent": {
        "consent_id": "550e8400-e29b-41d4-a716-446655440002",
        "dc_id": "550e8400-e29b-41d4-a716-446655440003",
        "dp_id": "550e8400-e29b-41d4-a716-446655440004",
        "consent_type": "urn:openfinance-ml:account-access-consent:v1.2",
        "consent_purpose": "pfm",
        "permissions": ["read_accounts", "read_balances", "read_transactions"],
        "expiration_datetime": "2025-12-31T23:59:59Z",
        "status": "authorized",
        "accounts": [
          {
            "account_id": "550e8400-e29b-41d4-a716-446655440005",
            "account_number": "1234567890",
            "account_name": "My Savings Account"
          },
          {
            "account_id": "550e8400-e29b-41d4-a716-446655440006",
            "account_number": "0987654321",
            "account_name": "My Checking Account"
          }
        ],
        "created_at": "2025-01-15T10:30:00Z",
        "updated_at": "2025-01-15T10:35:00Z"
      }
    }
  ]
}

Response Fields:

Authorization Details Fields

The authorization_details field contains critical consent and account information:

Validating the ID Token

The ID token is a signed JWT containing verified information about the authenticated user. You must validate the signature before trusting the token's contents.

ID Token Structure

An ID token is a JWT with three parts (header.payload.signature):

Header:

{
  "alg": "PS256",
  "typ": "JWT",
  "kid": "key1"
}

Payload:

{
  "iss": "https://auth1.sandbox.mya.ozoneapi.io",
  "sub": "dedfbc3c-1037-4c58-acd0-036c01715f0f",
  "aud": "550e8400-e29b-41d4-a716-446655440000",
  "iat": 1673647800,
  "exp": 1673651400
}

Signature: Cryptographic proof using OFP's private key (you verify with their public key)

Validation Steps

1. Extract the ID token from the response
2. Decode the JWT (don't trust yet - this is unsigned)
3. Extract the kid (Key ID) from the header
4. Fetch OFP's JWKS using the jwks_uri from the well-known endpoint
5. Find the matching public key by kid
6. Verify the signature using PS256 algorithm
7. Validate claims:
   • iss: Must match OFP's issuer (from well-known endpoint)
   • aud: Must match your client_id
   • exp: Must not be in the past (token not expired)
   • iat: Sanity check (issued at a reasonable time)

Example: Validating ID Token (Node.js)

const jwt = require('jsonwebtoken');
const axios = require('axios');

async function validateIdToken(idToken, wellKnownUrl, clientId) {
  try {
    // Step 1: Fetch OFP's well-known configuration
    const wellKnownResponse = await axios.get(wellKnownUrl);
    const jwksUri = wellKnownResponse.data.jwks_uri;
    const issuer = wellKnownResponse.data.issuer;

    // Step 2: Fetch OFP's JWKS (public keys)
    const jwksResponse = await axios.get(jwksUri);
    const jwks = jwksResponse.data;

    // Step 3: Decode without verification to get the header
    const decodedToken = jwt.decode(idToken, { complete: true });
    if (!decodedToken) {
      throw new Error('Invalid JWT structure');
    }

    const kid = decodedToken.header.kid;

    // Step 4: Find the public key with matching kid
    const key = jwks.keys.find(k => k.kid === kid);
    if (!key) {
      throw new Error(`Key with kid "${kid}" not found in JWKS`);
    }

    // Step 5: Convert JWK to PEM format
    const publicKey = jwkToSignatureBuffer(key);  // You'll need a JWK to PEM library

    // Step 6: Verify the signature
    const verified = jwt.verify(idToken, publicKey, {
      algorithms: ['PS256'],
      issuer: issuer,
      audience: clientId
    });

    console.log('ID Token validated successfully');
    console.log('User sub:', verified.sub);
    return verified;

  } catch (error) {
    console.error('ID Token validation failed:', error.message);
    throw error;
  }
}

// Call the function
validateIdToken(idToken, wellKnownUrl, clientId)
  .then(claims => {
    console.log('Trusted user claims:', claims);
  })
  .catch(err => {
    console.error('Authentication failed:', err);
  });

Example: Validating ID Token (Python)

import jwt
import requests
from jose import jwk
from jose.utils import base64url_decode

async def validate_id_token(id_token, well_known_url, client_id):
    try:
        # Step 1: Fetch OFP's well-known configuration
        well_known_response = requests.get(well_known_url)
        well_known = well_known_response.json()
        jwks_uri = well_known['jwks_uri']
        issuer = well_known['issuer']

        # Step 2: Fetch OFP's JWKS (public keys)
        jwks_response = requests.get(jwks_uri)
        jwks = jwks_response.json()

        # Step 3: Decode without verification to get the header
        unverified = jwt.get_unverified_header(id_token)
        kid = unverified.get('kid')

        # Step 4: Find the public key with matching kid
        key_data = None
        for key in jwks['keys']:
            if key['kid'] == kid:
                key_data = key
                break

        if not key_data:
            raise ValueError(f'Key with kid "{kid}" not found in JWKS')

        # Step 5: Convert JWK to PEM and verify
        public_key = jwk.construct(key_data)

        # Step 6: Verify the signature and claims
        verified = jwt.decode(
            id_token,
            public_key.to_pem(),
            algorithms=['PS256'],
            issuer=issuer,
            audience=client_id,
            options={'verify_signature': True}
        )

        print('ID Token validated successfully')
        print(f'User sub: {verified["sub"]}')
        return verified

    except Exception as error:
        print(f'ID Token validation failed: {str(error)}')
        raise

# Call the function
try:
    claims = validate_id_token(id_token, well_known_url, client_id)
    print(f'Trusted user claims: {claims}')
except Exception as e:
    print(f'Authentication failed: {e}')

Using the Access Token

Once you have the access token, proceed to:

• Section 9: Retrieving Account, Balance & Transaction Information - Use the access token to fetch account data, balances, and transaction history

Storing and Managing Tokens

Token Storage

1. Access Token: Store securely in memory or session (valid for ~1 hour)
2. Refresh Token: Store securely in encrypted storage (valid for longer period)
3. ID Token: Extract claims and validate (for identity), can be discarded after validation
4. Consent ID: Store with your application's session (needed for consent operations)

Token Refresh

When the access token expires (after expires_in seconds), use the refresh token:

curl -X POST "{{token_endpoint}}" \
  --cert /path/to/transport-certificate.pem \
  --key /path/to/transport-key.pem \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "x-fapi-interaction-id: 550e8400-e29b-41d4-a716-446655440000" \
  -d "grant_type=refresh_token" \
  -d "client_id={{CLIENT_ID}}" \
  -d "refresh_token={{REFRESH_TOKEN}}"

Common Errors

The token endpoint returns OAuth 2.0 and OpenID Connect error responses when the request fails.

HTTP 400 - Bad Request

HTTP 401 - Unauthorized

HTTP 403 - Forbidden

Validation Errors

Next Steps

Once you have obtained the access token:

• Retrieve Account Data - Use the token to fetch account details, balances, and transactions

Related Documentation

• Client Authentication Methods - Token exchange authentication options
• Section 7: Consent Authorization - How to obtain the authorization code
• Section 6: Creating a Consent - PKCE code verifier generation
• Section 2: Discovering OFP Endpoints - Well-known endpoint and jwks_uri