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 |
|
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 |
|
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"
}