As CSP, CLEAR returns refresh tokens in the OAuth request to mitigate the challenge of short-lived identity tokens while maintaining security standards and improving the user experience by reducing the frequency of identity verification.

Overview

Identity tokens used in for Individual Access Services (IAS) have a short expiration period but are required for every API request. Including refresh tokens eliminates the need for patients to repeatedly verify their identity at IAL2 level during a single session.

How it works

The access and identity tokens generated with the refresh token grant will have the same 1 hr lifespan as the original set of tokens.

How to use it

1. Initial Authentication Flow:
   • Complete the standard authentication process to obtain an ID token
   • The response will now include a refresh token alongside the ID token
   • Store the refresh token securely on your backend
2. Token Refresh Process:
   • When an ID token expires, use the refresh token to request a new access and identity token
   • Send a POST request to the token endpoint with the refresh token in the body
   • Receive a new access, identity, and refresh token in the response
3. Token Management:
   • Implement proper token storage and rotation
   • Monitor token expiration and proactively refresh when needed
   • Handle scenarios where refresh tokens may be invalidated

Example Request

curl --location 'https://verified.clearme.com/integrations/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cookie: xx' \
--data-urlencode 'client_id=urn:oid:1.11.222.2.333333.4.4444.5.5.55555.6' \
--data-urlencode 'refresh_token=aa\_bbbbbbbbbbbbbbb.ccccccccccc\_dddddd' \
--data-urlencode 'scope=offline openid offline_access' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'client_secret=xxxxxxxuuuuuuuYYYYYYY'

Example Response

{
  "access_token": "new_identity_token",
  "expires_in": 3600,
  "id_token": "new_identity_token",
  "refresh_token": "new_refresh_token",
  "scope": "offline openid offline_access",
  "token_type": "bearer"
}

Security considerations

1. Token Storage: Refresh tokens must be stored securely on your backend systems, never exposed to client-side code or stored in browsers.
2. Token Revocation: Implement proper procedures for token revocation when users log out or change security settings.
3. Monitoring: Monitor token usage patterns to detect potential security issues.