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.

Authenticating Requests

Frollo uses the API Key to authenticate individual API requests. All requests requiring authentication should provide the Authorization header.

Authorization header format:

<API KEY>

Example:

Authorization: abcdef12345

Using Client APIs via the Management API

The Client API can also be used in an application context for M2M purposes.

To use the Client APIs within an M2M context 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.

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

Set the Authorization header to your API Key (this is the same as when access the Management API)
Set a X-User-Id header to contain the ID of the User you are acting as
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 are example requests of how you would consume the Get User Details API via both methods. The differences have been marked in bold.

User Scoped - Client API Directly

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

M2M Scoped - Client API via Management API

Note: API Key or OAuth2.0 Client Credential can be used for authorisation

Request Property	Value
Method	`GET`
URL	/api/admin/client/v2/user/details
Headers	`Authorization: Bearer $access_token` `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"
}