Flow

🔐 To use the Fintecture API in the production environment, the first mandatory step is to sign all HTTP requests using the HTTP Signature system. This ensures the authenticity and integrity of every request sent to the server.

Prerequisites

Before generating an OAC (Organisation Access Credentials) token, ensure that Fintecture has created the following on your behalf:

• ROOT Organisation Node - The top-level organization structure
• OAC credentials - Contains the organisation_node_id that will be present in OAC tokens

From the OAC credentials provided by Fintecture, you will need:

• client_id - corresponds to oac_uuid
• client_secret - corresponds to uuid

Steps

1. Contact Fintecture to request the creation of your ROOT Organisation Node and OAC credentials
2. Receive your client_id and client_secret from Fintecture
3. Encode your credentials using Base64 (Basic base64({client_id}:{client_secret})) to generate the Authorization header
4. Request an access token using your credentials, the desired organisation scopes, and the Authorization header
5. Extract following information from provided response body:
   • access_token is to be used for endpoints' calls
   • type will be oac_token
   • expires_in allows you to know token's duration validity (default: 3600 seconds)
   • refresh_token can be used to obtain a new access token
   • scope lists the granted permissions
6. Use access_token for every organization management endpoint requiring Bearer authentication
7. Check regularly expires_in and before access token's expiration, request a new one using the refresh token

Scopes

The OAC token supports the following scopes for organization management:

• organisations:read - Read organization structure
• organisations:write - Modify organization structure
• companies:read - Read company information
• companies:write - Create/modify companies
• users:read - Read user information
• users:write - Create/modify users
• applications:read - Read application configurations
• applications:write - Create/modify applications

You can request multiple scopes in a single token by separating them with spaces in the request body.

Example Request

Endpoint: POST https://api-sandbox.fintecture.com/oauth/accesstoken

Headers:

Authorization: Basic base64({client_id}:{client_secret})
Accept: application/json
Content-Type: application/x-www-form-urlencoded

Body (x-www-form-urlencoded):

scope=organisations:read organisations:write
grant_type=client_credentials

Example Response

{
    "access_token": "eyJh...",
    "type": "oac_token",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "eyJhb...doQ",
    "scope": "organisations:read organisations:write users:read users:write"
}