ID tokens are Json Web Tokens (JWTs) that can be used as bearer tokens. They expire after 1 hour and must be refreshed with a refresh token, which expires after 30 days.

Create an ID Token

To create an ID token make a request that looks like this:

curl --request POST 'https://api.bridgeft.com/v2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=YOUR_EMAIL' \
--data-urlencode 'password=YOUR_PASSWORD' \
--data-urlencode 'grant_type=password'

You'll receive a response that looks like this:

{
    "ExpiresIn": 3600,
    "TokenType": "Bearer",
    "IdToken": "eyJraWQiOiIwMnFuVWJhQ0JXS1hveTFRRWQ1OE9kM0...",
    "RefreshToken": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NN..."
}

The IdToken value can be used as a bearer token and expires in one hour. The RefreshToken is used to receive a new ID token after it expires.

Using ID Tokens

To authenticate future requests, set the Authorization header to the value Bearer ID_TOKEN, replacing ID_TOKEN with the value of IdToken from the above response.

For example, here's how to make an authenticated request to list all accounts:

curl --request GET 'https://dev.api.bridgeft.com/v2/account-management/accounts' \
--header 'Authorization: Bearer ID_TOKEN'

Where ID_TOKEN is the ID token JWT.

Expiration and Refresh

If you make an API request and receive a 401 Unauthorized response with the following corresponding json message, it menas the token has expired:

{
    "message": "Unauthorized"
}

You should refresh the token using the RefreshToken value from the above response.

To refresh this token, make the following request:

curl --request POST 'https://dev.api.bridgeft.com/v2/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'refresh_token=REFRESH_TOKEN' \
--data-urlencode 'grant_type=refresh_token'

Where REFRESH_TOKEN is the refresh token obtained from the password grant type request.

Json Web Token Contents

Both ID and refresh tokens are Json Web Tokens. ID tokens can be inspected for additional details using the tools and libraries available from jwt.io

Some of the useful standard claims are:

exp: the expiration time as a unix epoch
iat: the timestamp when the token was issued as a unix epoch

An additional custom bft:user claim is provided with the following properties:

user_id: the ID of the user
profile_id: the ID of the user's profile
firm_id: the ID of firm to which the user belongs
is_firm_user, is_client_user: boolean values indicating whether the user is a firm user or end-client user
firm_ids: a list of firm IDs the user has access to; relevant for consolidated firms