HomeGuidesRecipesAPI Reference
Log In
API Reference

Authentication

Get Started with Falcon APIs and test them. Know about gateway URL, authentication, and more.

Overview

This guide contains information about how to use Falcon’s RESTful API features to manage your products and programs. Falcon APIs are completely RESTful, and all our responses are returned in JSON.

Stage Environment

The APIs have endpoints connected with our staging environment. It does not affect the live data or interact with the production environment.

API Gateway URL (Base URL)

The Falcon API Gateway URL is https://credituat.falconfs.com/. You should include this URL before each API endpoint to poll APIs.

API Authentication

This API will take a client ID and client secret key before accessing any Falcon system's protracted APIs.

While logging in for the first time, you should send a request to the Falcon system to create an access token. The system returns a JSON Web Token (JWT). You should include your client ID and client secret in the request's headers. The access token has a predefined lifetime of 10 minutes. The exp field in the JWT contains the date/time of expiration in Unix Epoch time. You can see the same expiration time in the access token generation API response.

After the access token expires, the Falcon system rejects additional requests. If you make a request using an expired token, the API request returns an Unauthorised Response.

📘

Handy Tips

You should pass this JWT in subsequent APIs as a bearer authentication header.

Use this endpoint to create an access token.

POST/login
Curl -X POST https://credituat.falconfs.com/api/v1/login
-H "x-client-id: {{clientId}}" \
-H "clientSecret: {{clientSecret}}" \
-H "x-tenant-id: {{tenantId}}" \

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJXc0NfLXdtYkYxMVYwaThqTG1EczVWOTg5UllfbEs3UFZ4UWw0WDFHV1NBIn0.eyJleHAiOjE3MjA1OTUwNjYsImlhdCI6MTcyMDU5NTAwNiwianRpIjoiZWUxYTI4ZTMtYWNkNS00MTc5LTlkNGYtYTBjYjA5YmExNzAyIiwiaXNzIjoiaHR0cHM6Ly9jcmVkaXR1YXQuZmFsY29uZnMuY29tL2lkYW0vcmVhbG1zL2t2YiIsImF1ZCI6ImFjY291bnQiLCJzdWIiOiI3YjI3YjAyMS04YWU2LTQzOTUtOGU3Yy00OGRiMjIxYzVlYWYiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJiYW5rX2t2YiIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsiaHR0cDovL2xvY2FsaG9zdDo4MjE5Il0sInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJkZWZhdWx0LXJvbGVzLWt2YiIsIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJiYW5rX2t2YiI6eyJyb2xlcyI6WyJjbGllbnQtYWRtaW4iXX0sImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImNsaWVudEhvc3QiOiIxMC40LjAuMzMiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsInByZWZlcnJlZF91c2VybmFtZSI6InNlcnZpY2UtYWNjb3VudC1iYW5rX2t2YiIsImNsaWVudEFkZHJlc3MiOiIxMC40LjAuMzMiLCJjbGllbnRfaWQiOiJiYW5rX2t2YiJ9.u2akRoVIrg_Kx9uDIDU30kTDHekEAayKrr2JQXatMgHfH9bOUqpEfhshXErwZ8ziquc5fzSz6N_dQBCwTxJ_6OScMoGHyS9i23XUYG_lZS3BL9gT4CNmXQpBSN-imZV81kfOph7IX3c8u5eJs2XX9qhz7V2faZqyKElGucqdF7gt_ZOgA71r7QBcC3mQbTyoKDAYFkNYl2CB1lSzl0sv3484dIEx1xN2VLLJjMUee2huxQ1PSzBdD4oSxw0Rf8O4GK1TdR2TPQr-dLTvMajqDy7EKAA0SOTFxMQEcyxxOA_7TzPeia5TJKPsWTlNJ3lMVnsY6Behxi9trapWBlHPIQ",
    "expires_in": 60,
    "refresh_expires_in": 0,
    "refresh_token": null,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": null,
    "scope": "email profile"
}

Encryption and Decryption

We use the Symmetric key to Encrypt and Decrypt all requests and responses.

EnvironmentKey Share
Non-ProductionFalcon will share the key for encryption and decryption of requests and responses.
ProductionBank shares a key, and Falcon configures it for encryption and decryption of requests and responses.
Class Test 
{
    String name;
    String email
}

Encryption Logic

Input

  • Request Payload
  • Secret Key (shared beforehand)

📘

Handy Tips

The Class Test is an example. The Request Payload should be the request body mentioned in each API’s contract.

public static String encrypt(Object request, String key) throws Exception {
        String stringifyRequest = new ObjectMapper().writeValueAsString(request)
        SecretKeySpec secretKeySpec = new SecretKeySpec(Base64.getDecoder().decode(key), "AES");
        Cipher cipher = Cipher.getInstance("AES");
        cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec);
        byte[] encryptedBytes = cipher.doFinal(stringifyRequest.getBytes());
        return Base64.getEncoder().encodeToString(encryptedBytes);
}

{
  String :  "mkik5tkxnHBJRrJBWtkFj2bKUePa/TJwBA2BOgDtkS8="
}

This encrypted string is passed in the request body instead of the plain JSON body. Headers will remain as described in the API contract in this doc.

curl --location --globoff '{content-path}/cc-open-api/falcon/v2/user' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}' \
--header 'x-tenant-id: kvb' \
--data 'mkik5tkxnHBJRrJBWtkFj2bKUePa/TJwBA2BOgDtkS8='

You will receive a string as a response. Similar to the request body, the response will be an encrypted string instead of a plain JSON body. You should decrypt it to consume it.

Decryption Logic

Input

  • Response String (encrypted)
  • Secret Key (shared beforehand)
public static String decrypt(String encryptedString, String key) throws Exception {
        SecretKeySpec secretKeySpec = new SecretKeySpec(Base64.getDecoder().decode(key), "AES");
        Cipher cipher = Cipher.getInstance("AES");
        cipher.init(Cipher.DECRYPT_MODE, secretKeySpec);
        byte[] decryptedBytes = cipher.doFinal(Base64.getDecoder().decode(encryptedText));
        return new String(decryptedBytes);
 }

You will receive a string as a response. This string is a stringified JSON that can be converted to the respective JSON as shared in the contract of each API.

Header Information

Below are the request and response headers you should pass while polling APIs.

Request Headers

All these headers are mandatory while polling APIs.

Header NameData TypeDescription
x-tenant-idstringThe tenant ID. For example, falcon.
AuthorizationstringThe auth token that is received as a response from the authentication API.

Response Headers

The following is the header received in the response of the APIs.

📘

Handy Tips

Save this x-trace-id in case of any difficulties in the API and tag along with the resolution request.

Header NameData TypeDescription
x-trace-idstringTrace id is a unique identifier associated with each request. You can use this ID for any request identification or issue resolution purposes.
↑