Flow

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