Getting Started

Obtaining a session token in the backend

1. On your backend server, serialise and base64 encode your Frankie API Credentials using ":" as a separator
- "CUSTOMER_ID:API_KEY", if you don't have a CUSTOMER_CHILD_ID

You can do the encoding online here - Online encoder


echo -n 'CUSTOMER_ID:CUSTOMER_CHILD_ID:API_KEY' | openssl base64
  1. To get a secure temporary token, which will allow the Smart UI to make requests on your behalf, send a post request to ${frankieUrl}/auth/v2/machine-session, including the serialised credentials in the header parameter "authorization". You may also optionally pass (but highly recommended) two JSON fields in the body: referrer and permissions. Read more about these fields next.


authorization: machine {encoded credentials}

Although optional, you should limit the permissions included in the temporary token to a specific applicant reference, denying any attempt to access other applicant's details.


    "permissions": {
        "preset": "smart-ui",
        "reference": "${theApplicantReference}"

Where theApplicantReference is the same string passed to the Smart UI initialisation function.

Optionally include a field "referrer" in the request's body, with the pattern to be used to verify the url from which calls can be made using the token. The referrer sent by the browser must match the referrer URL pattern in the JWT for the Smart UI to successfully authenticate

The referrer is based on the Google Chrome match pattern URLs. URLs can contain wild card characters. You can read more about it here match pattern.

**Permitted referrer patterns are as follows:

Referrer PatternsReferrer Patterns

Referrer Patterns

An example of a valid referrer is


Whilst not required, this option is highly recommended, as it secures your short lived token from being used from unknown sources and guarantees that other malicious websites cannot reuse the JWT in case it is lost. The only reason not to use it is in the case that your frontend is configured not to send Referer (sic) headers. Read more.


    "referrer": "" || "*://*"

Sample Postman request collection
You can use this postman collection to do the API call to our backend

Sample curl operation

#! /bin/bash
credentials=$(echo -ne "$CUSTOMER_ID:$API_KEY" | base64);
curl -vs --request POST '' \
--header "authorization: machine $credentials" \
--header 'Content-Type: application/json' \
--data-raw "{\"referrer\": null, \"permissions\": { \"preset\": \"smart-ui\", \"reference\": \"$applicantReference\" }}" 2>&1 | grep "token:"
  1. The response will contain a short lived api token in the header parameter "token"
    This token is valid for 1 hour and is refreshed on each successful call to the backend.


token: {Frankie generated token}

Note: The successful response body which will be a HTTP 200 will include a configuration object that will most likely not be useful to your use case, but is used by our frontend to customise its behaviour. The configuration includes a message dictionary that might seem like error messages, but they aren't. You may disconsider anything found in the successful response body.


Keep your secrets

Your Customer ID and Api key are both secret information and should not be included in frontend code. For that reason make sure to request the /machine-session endpoint and that all code until this point was done in your backend server.


Know your Headers...

Please do not reference the headers by numeric index (as an array lookup).
The location of the header in the authentication response is not guaranteed to be the same for all requests.

ie: instead of headers[12], use headers["token"].
Numeric lookup will likely break your implementation should the order or number of headers change.

Backend steps until here

Frontend steps starting here

Initialise Smart UI in the frontend

  1. Add both the link to the desired font family and script tag to the Smart UI .js file in the head of the webpage. You need to initialise the Smart UI by calling javascript function in the global frankieFinancial object, where you pass the configuration object, the session token as ffToken (see Obtaining an Api Token above) and the applicant reference. The initialisation needs to be done after the page is mounted, so the widget element is already available. In plain html that should be done in the event body.onload (see snippet below).

  2. "Applicant reference" is your own internal identification for that applicant, not Frankie's entity id. If you have previously sent this applicant's data to Frankie using that Applicant reference, the service will automatically retrieve that data and attempt to pre-populate this Smart UI with the data available.

Note: When initialising, the widget makes an applicant search request to find out if the applicant reference already exists and if so, to prefill the widget with the applicant details. When the applicant is not found, the request returns a HTTP response of 404 not found, which might log a network error on the console, but that response is expected and can be ignored.

<!-- viewport meta is recommended for responsive pages -->
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0,user-scalable=0"/>
<!-- install your font, if you don't already have it -->
<link href=",[email protected],300;0,400;0,700;1,300;1,400&display=swap" rel="stylesheet">
<script src=""></script>
    function onLoaded() {
            ffToken: "XXXXXXXX...",
            applicantReference: "some-applicant",  /// the string reference that will be injected into this applicant's data, will be used to prefill data and can be used to request their details aftwerwards, both via Frankie API and Frankie Portal,
            height:"500px", // Passing height, width is optional. By default they're calculated based on full screen size
            width:"900px", //
            config: {  /// the configuration object, see the configuration section below
                frankeiBackendUrl: "https://defaults-to-frankie-production-url",
                successScreen: {
                  ctaUrl: "javascript:alert('Callback for successful onboarding')"
                failureScreen: {
                  ctaUrl: "javascript:alert('Callback for failed onboarding')"
                documentTypes: ["DRIVERS_LICENCE", "PASSPORT", 'NATIONAL_HEALTH_ID'],
                acceptedCountries: ["AUS", "NZL"],
                ageRange: [18, 125],
                organisationName: "My Organisation",
    var body = document.getElementsByTagName("body")[0];
  1. Add the html element wherever you want it to be mounted on your webpage.

Did this page help you?