Overview - Connect to your FNZ API
Connect to your FNZ platform via the FNZ Connect API Gateway (ex - Tapico Platform)
The acquisition of the Tapico Platform by FNZ has led to the launch of the FNZ Connect API Gateway. FNZ Connect allows consumers and integrators of FNZ powered platforms and products to connect to their respective APIs including the FNZ core platform APIs - OpenPlatform API.
This page is an end-to-end guide that covers how to connect to an FNZ powered platform's OpenPlatform APIs using FNZ Connect.
Registering for the Developer Portal
FNZ Connect maintains two separate environments for production and sandbox (non-production). Each has its own independent developer portal and base API gateway URLs used in all subsequent API requests.
Environments
Environment | Purpose | Dev Portal | API Base URL |
---|---|---|---|
Sandbox | Testing and developing your Application. In the sandbox, you will be able to connect to your platform test environment(s). | https://sandbox.tapico.io/ | https://api.sandbox.tapico.io/ |
Production | Connecting to your production platform instance. | https://prod.tapico.io/ | https://api.prod.tapico.io/ |
Registering Users
You can self register for either of the FNZ Connect environments by selecting Register
on the landing page and following the prompt.
Password Policy
Take some simple steps to make your password as secure as possible.
Your Password must:
- be at least 8 characters
- include a number
- include an upper case character
- include a lower case character
Generally speaking, longer passwords are better than shorter ones. Some people like the "pick three random words" approach. We also encourage you to turn Multi-Factor Authentication on in your settings.
Setting up an Organisation
Resources on FNZ Connect are managed in the context of an Organisation. An Organisation represents a related group of individuals who collaborate on building services (Upstreams) or applications. This could be anything from your entire company (in smaller organisations), or your immediate team.
If you have been invited to join an existing Organisation you can proceed under that Organisation. If you are the first to register, you'll need to create a new Organisation before you can use any of the gateway services.
Once you have created an Organisation you will be able to:
- Invite your colleagues to join you on the gateway.
- Create an Application
- Request access from the application to connect to your platform APIs.
1. Create an Organisation.
Navigate to the Organisations menu on the lefthand side and select Create
. Give your Organisation a name and a brief description. Also feel free to upload your organisation's logo to be used as an icon.
2. Assign Members to your Organisation.
Invite your colleagues to become a Member of your Organisation and allow them to create and manage Applications on your behalf. This is optional.
Invite them using their email address and assign a specific access level.
- Owner: Highest access level. Owners can create and edit Applications under any Organisation they belong to as well as invite and remove members.
- ReadWrite: Same access as an Owner without the ability to manage members.
- ReadOnly: User's with ReadOnly permissions can only view resources relating to the Organisation they have ReadOnly access to. They cannot create or edit.
Default Permissions
When you create an Organisation you will automatically be given Owner level permissions.
Creating an Application
An Application is necessary to access and send API requests to a particular FNZ platform.
Under your Organisation you can create as many Applications as you like.
1. Create an Application
Navigate to the Applications menu on the lefthand side and select Create
. Populate the required fields and select Save
to create the application.
Required Fields
There are a lot of fields that can be add for an application. However, for this scenario (connecting to the OpenPlatform API) only the 'Name' field is required to be populated.
Subscribe as a consumer of a platform's OpenPlatform API
Once your Organisation and Application have been created, the next step is to subscribe to your target platform's OpenPlatform API Service Pack. In the sandbox environment there maybe multiple service packs available for you to select, one for each test environment available under your platform.
1. Select a OpenPlatform API Service Pack
Under Application → Services, click + ADD
to view the available Service Packs for your organisation. Select one and follow the prompts to request access. This will have to be approved by the FNZ OpenPlatform API team. You will receive an email notification once it have been approved.
Availability of OpenPlatform API Service Packs
FNZ OpenPlatform API team needs to setup each individual service pack and permission them to your organisation. If you cannot see a service pack for the FNZ environment you expect please reach out to a OpenPlatform API team member directly or use the inbuilt support available in the FNZ API Gateway.
2. View API Reference Spec
Once the subscription to the platform's service pack has been approved by an owner of the service pack. You will be able to access the API (see API Authentication) and view the API reference specification for the APIs.
API Authentication
With an Organisation and Application created and an approved subscription to a OpenPlatform API Service Pack you can access the API.
1. Generating API Credentials
Under the Application → Basic Details page for your Application towards the bottom is a section titled API Credentials
. Select Create
and make a note of your API Credentials (client_id
and client_secret
).
IMPORTANT
You cannot retrieve the secret after the initial creation. If you lose the secret you must revoke and recreate your application credentials.
2. Obtain a JWT using the client_credentials flow
The OAuth Client Credentials Grant flow provides a machine-to-machine auth mechanism for accessing the APIs. Your application must present its client_id
+ client_secret
to request a JWT, and use this token in subsequent requests to the OpenPlatform API.
Additionally you need to specify resource
and scope
to identify the services you are obtaining access to via the gateway. The resource parameter is an implementation of RFC 8707 Resource Indicators for OAuth 2.0. It controls which services the resulting token is permissioned to access. In this case it limits access to OpenPlatform APIs for a specific platform.
curl --location --request POST 'https://api.sandbox.tapico.io/v1/oauth/token' \\
--header 'Content-Type: application/json' \\
--data-raw '{
"client_id": "{{client_id}}",
"client_secret": "{{client_secret}}",
"grant_type": "client_credentials",
"resource": "{{resource_indicator}}",
"scope": "{{scopes}}",
}'
The specific resource
and scope
values needed are visible under the Application Subscribed Service Packs view. Select your Application and then select Services
on the left hand menu. All of the your approved Service Pack will be listed here.
API Reference and Documentation
Access to the FNZ OpenPlatform API reference and documentation is currently accessed through a separate portal.
You will be provisioned access to the documentation separately. If you do not have access, please get in touch with your FNZ contact or raise a support request.
Webhook Setup
1. Configuring Webhooks
FNZ OpenPlatform Webhooks are managed via Application → {Your Platform Service Pack} → Webhooks.
This supports the following functionality:
- Add or remove webhooks
- Enable or disable a webhook
- Set or modify the event subscriptions for a webhook
2. Webhook retries
FNZ OpenPlatform Webhooks support configurable retry schedules, including exponential back-off, thus event ordering is not guaranteed.
Currently, these settings must be manually configured by FNZ. Please contact FNZ through your existing support channels if you wish to modify this configuration.
Updated 3 months ago