Assertion Usage

For a limited set of situations involving offline transfer of authentication data we support using Assertions backed by an authorization Grant policy to obtain access tokens. An assertion must be obtained from Fanatics ID and cannot be created externally.

Obtaining an Assertion

Currently this feature is only available for FanCash redemption and the Assertion can be obtained by scanning a QR code shown by a user.

To direct the user to the proper page, use the following deeplink template:

https://id.fanatics.com/account/fancash?client_id={client-id}&redirect_uri={redirect-uri}&campaign_id={campaign-id}

The redirect_uri will not be honored in this scenario but it must match the scheme and host of a redirect_uri registered with the OAuth2 client.

QR Code Contents

The QR code will contain a JSON object with the following structure:

{
    "balance": "10.000000",
    "assertion": "eyJhb..."
}

The balance value represents a hint to the users FanCash balance. The caller should lookup the current balance to verify.

The assertion should be provided as-is to the token exchange endpoint.

Token Exchange

The assertion obtained through the QR Code must be exchanged for a user access token to use with loyalty APIs. The token exchange may be performed through either the UI or Native API services.

Request

This endpoint conforms to OpenID Token Endpoint. Please be aware that the body is sent form encoded with the content type application/x-www-form-urlencoded.

For the token exchange you will send the following fields.

Name
Value

grant_type

jwt_bearer

assertion

The string encoded JWT Bearer Assertion provided by Fanatics ID.

client_id

The client_id assigned to your OAuth2 Client.

client_secret

This is your client secret that was generated when the client was configured.

redirect_uri

A redirect URI registered with the OAuth2 client, must match exactly.

scope

A space delimited list of scopes requested for the token to access. For this use case the scopes are controlled by the underlying grant policy associated with the campaign ID. This value is OPTIONAL for the `jwt_bearer` grant type.

Response

Access tokens must be treated as extremely sensitive. They should be stored securely on your server and should never be sent anywhere except our services. Do not send them back to end user clients or return them in a response from your servers.

Name
Description

access_token

This token can be used to call any of our APIs that you have the right permissions and scopes to call.

expires_in

The number of seconds the access token is good for.

id_token

A JWT that contains information about the user. Please see ID Token for more information.

refresh_token

A refresh token that can be used for generating a new access token after the current one expires. This will only be returned if the Grant Policy allows it. If no refresh token is available, a new token exchange can be used to obtain a new access_token until the policy expires. See Refresh Token for more information.

token_type

Bearer

Documentation

OIDC Token

post

Token Endpoint as described in https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint. A user access token can be passed as a scope to associate the account to create user specific, 'client_credentials', server tokens as described in https://datatracker.ietf.org/doc/html/rfc6749#section-4.4.

Body
client_idstringRequired

Your OAuth2 client id

client_secretstringRequired

Your OAuth2 client secret

codestringOptional

The OAuth code used for retrieving a bearer token

grant_typestringRequired

Grant type

partner_session_idstringOptional

Any session ids you want us to persist on the session

partner_stream_idstringOptional

Any session ids you want us to persist on the session

redirect_uristringOptional

The OAuth2 redirect URI

refresh_tokenstringOptional

The OAuth refresh token.

scopestringRequired

A space separated list of scopes. To extend a user token for a token with broader scopes the original access token should be before the scope list followed by a space.

assertionstringOptional

The JWT assertion to exchange for an access token when grant_type is jwt_bearer.

Responses
200

tokens

application/json
post
POST /v1/oauth2/token HTTP/1.1
Host: 
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 211

"client_id='text'&client_secret='text'&code='text'&grant_type='text'&partner_session_id='text'&partner_stream_id='text'&redirect_uri='text'&refresh_token='text'&scope='text'&assertion='text'"
{
  "access_token": "fiatz2H1kXuV59EdN_jeCA32qHuBOz...",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJFZERTQSIsIdsdjfbgksu...",
  "refresh_token": "firt6tsF90LTf8LYCYPtdh8q4qr3c...",
  "token_type": "Bearer"
}
PreviousPoint of Sale

Last updated