Getting Started

This page explains how to authenticate with Data Core and make your first API call to a connector endpoint.

Architecture

The Data Core framework sits between your application and external service providers. Your application sends a REST request to Data Core, which authenticates, routes, and translates the call to the appropriate provider API. The response follows a standardized format regardless of the provider.

Base URL

All connector endpoints documented on this site use relative paths (for example, /api/loqate/v1/find). To form the full URL, prepend your environment's Data Core base URL:

Copy 
https://<your-data-core-base-url>/api/loqate/v1/find

 

Authentication

Data Core uses OAuth 2.0 (client credentials flow) via Keycloak for API authentication. Each request must include a valid Bearer token in the Authorization header.

Obtaining a Token

Copy 
POST https://<keycloak-url>/realms/<realm>/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<your-client-id>
&client_secret=<your-client-secret>

 

The response contains an access_token with a limited lifespan (typically 5 minutes). Cache and reuse the token until it expires.

Using the Token

Include the token in every API request:

Copy 
GET https://<your-data-core-base-url>/api/loqate/v1/retrieve
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

 

Quick Start: Your First API Call

This example calls the Loqate address lookup endpoint. Replace the placeholder values with your environment details.

  1. Get an access token

    Copy 
    curl -X POST "https://<keycloak-url>/realms/<realm>/protocol/openid-connect/token" \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

  2. Call the connector endpoint

    Copy 
    curl -X POST "https://<your-data-core-base-url>/api/loqate/v1/find" \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "address": {
          "postalCode": "EC4V 4BJ",
          "countryNameAlpha2": "GB"
        }
      }'

  3. Review the response

    Copy 
    {
      "addressList": [
        {
          "id": "GB|RM|B|55605138|ENG",
          "text": "Old Change House, 128 Queen Victoria Street",
          "addressType": "Address",
          "additionalFields": {
            "description": "London, EC4V 4BJ"
          }
        }
      ]
    }

 

Integration Patterns

Data Core connectors can be called from multiple contexts:

Pattern

Description

Documentation
Server automation scripts Call connectors from FintechOS Platform server-side scripts using Web API client libraries with built-in auth. Calling Connectors from the FintechOS Platform
Direct REST calls Call connector APIs directly over HTTP from any client (Postman, external systems, microservices). Use the authentication flow described above.

 

Standard Error Format

All connectors return errors in the same JSON structure:

Copy 
{
  "status": 400,
  "title": "Bad Request",
  "detail": "Description of what went wrong",
  "instance": "/api/loqate/v1/find",
  "timestamp": "2026-06-24T10:30:00Z"
}

 

For upstream failures (when the external provider is unreachable or returns an error), the response includes a dependency object with the provider's original error details.