Introduction
Changelog
Authentication
Headers
Errors
Rate Limiting
OAuth 2.0
User
Devices
Aggregation
Bills
Budgets
Challenges
CDR
Configuration
Events
Goals
Messages
Pay Day
Payments
Reports
Surveys
Calculators
Images
Users
Accounts
Transactions

Authentication

The Frollo APIs support two authentication types. In a user context OAuth 2.0 is supported for the Client APIs. In an application context both OAuth 2.0 (Using Client Credentials grant) and API Key based authentication is supported is supported to access both the Client and Management APIs.

OAuth 2.0

OAuth 2.0 authentication is supported for the Client APIs and Mangement APIs. Any OpenID Connect compatible identity provider can be used with configuration or Frollo can act as the identity provider if required.

We recommend using OAuth 2.0 with Client Credentials grant type for accessing the Management API.

Grant Types

The Frollo identity provider supports the following grant types:

  • Resource Owner Password Credentials
  • Authorization Code
  • Authorization Code with PKCE
  • Client Credential (Management API only)

For 3rd party identity providers any grant type can be used as long as the following scopes are claimed.

Using the Client Credential grant type will limit access to only the Management API.

Scopes

Frollo requires the following claims:

  • openid
  • email

Additionally the Frollo identity provider requires the following claims to obtain a refresh token:

  • offline_access

Authenticating Requests

Frollo uses the standard OAuth 2.0 bearer token to authenticate individual API requests. All requests requiring authentication should provide the Authorization header.

Authorization header format:

Bearer <ACCESS_TOKEN>

Example:

Authorization: Bearer xxxxx.yyyyy.zzzzz

API Key

The Management API is also accessible in an application context using the API Key. The Client API can also be used in an application context for M2M purposes.

To use the Client APIs with the API Key the target user must be identified via an X-User-Id header. The use-case for this is so that these APIs can be consumed on a user’s behalf via a backend connection. Read on for more details.

In order to connect to these APIs using this method, you need to do the following three things:

  1. Set the Authorization header to your API Key (this is the same as when access the Management API)
  2. Set a X-User-Id header to contain the ID of the User you are acting as
  3. Replace all /api URL prefixes in this document with /api/admin/client

Please note that the following headers are not required when accessing this API via this method:

  • X-Bundle-Id

  • X-Software-Version

  • X-Device-Version

Example

Below is an example of how you would consume the Get User Details API via both methods:

  • OAuth 2.0 - when consuming it from an app or backend integration

  • API Key - when consuming it from a backend integration

The differences have been marked in bold

OAuth 2.0

Note: The below request assumes the client has gone through the OAuth 2.0 login flow in order to obtain an access token.

Request Property Value
Method GET
Url /api/v2/user/details
Headers
  • Authorization: Bearer $access_token
  • X-Api-Version: 2.0
  • X-Bundle-Id: us.frollo.Frollo
  • X-Software-Version: V1.00-B1
  • X-Device-Version: IOS10.0.0

API Key

Request Property Value
Method GET
Url /api/admin/client/v2/user/details
Headers
  • Authorization: $api_key
  • X-Api-Version: 2.0
  • X-User-Id: 32

OTP

Certain Client API calls will require additional security measures to be undertaken by the client when being called. In these scenarios an OTP will be requested from the user by means of an error code and the request will need to be resubmitted with the OTP attached.

Detecting an OTP is Required

If an OTP is required the endpoint will return an error by sending HTTP status code 401 and the JSON body will contain the following error details:

HTTP Status Code: 401

{
    "error" : {
        "error_code": "F0120", 
        "error_message": "OTP Required",
    }
}

When this is received a user will automatically be sent an OTP to their device so there is no need to request one manually.

Sending an OTP

Once the user has received an OTP the request will need to be re-sent and and the OTP appended to the request. This can be done by appending the OTP to the header of the request.

X-User-Otp: 123456

Requesting a New OTP

If the user does not receive an OTP or needs to request another OTP due to expiry then the OTP endpoint can be called.

Example:

POST /otp

{
  "method": "sms"
}

Enrolling or Updating OTP Details

If the user does not have a phone number enrolled on their account or needs to update their phone number they can use the Update User Details endpoint to change the phone number and then confirm the phone number using the Confirm User Details API.

First the details are updated, providing an OTP from the old phone number if one already exists.

PUT /user/details

Header: X-User-Otp (Required only if there is an existing mobile_number)

{
  "mobile_number": "+61412345678"
}

Next the details are confirmed by the user once they receive an OTP to the new number to confirm they own that phone number.

POST /user/details/confirm

Header: X-User-Otp

{
  "mobile_number": "+61412345678"
}