Authentication methods

The Open Data API can only be accessed alongside an authorization token that must be present in every request, in a special header. Currently, we are offering two security schemes for authorization, OAuth token and Api key token. You will have the option to use one or the other at any time, but not both simultaneously. If you call any service without authenticating the request, you will get a 401 error.

🔑 Api key

Api key is the most straightforward approach, as you only have to pass your account's unique key as a parameter in a special header of your HTTP request, called x-api-key.

Initially this value will be provided to you when you enable your account with Khipu, so it is your responsibility to save your key and keep it safe at every moment, being careful not to share it to unwanted users or commit it in your source code repo. ⚠️ Remember that your key has full access and privileges to interact with the API, and each request count towards your account's billing.

API Call

A sample call using your Api key would look like this:

curl --request GET \
  --url https://api.khipu.com/target-resource \
  --header 'x-api-key: <value of your assigned Api key>' \
  --header 'Content-type: application/json'

🔐 OAuth token

OAuth 2.0, which stands for “Open Authorization”, is a standard designed to allow a website or application to access resources hosted by other web apps on behalf of a user.

You can also use OAuth 2.0 client credentials grant to access our protected APIs, an approach known as two-legged auth. First you (or your application) must communicate with our identity server to generate an access token using the credentials (pair of client_id and client_secret values) provided to you when you enable your account with Khipu. Once the access token (also known as "bearer token") is received, it must be included in the Authorization header of the request, using the prefix "Bearer". Here's a quick summary with the steps required to generate the JWT and call a protected resource (it is assumed you already have the credentials provided when you registered an account in Khipu).

Request an access token

This is done with a POST call to the API method that generates the token. In the query parameters of the call you must specify the grant type "client credentials" to use the correct flow in our identity server.

Example using cURL:

curl --request POST 'https://api.khipu.com/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<your-client-id-goes-here>' \
--data-urlencode 'client_secret=<your-client-secret-goes-here>' \
--data-urlencode 'grant_type=client_credentials'

Parameters

Extra security

It is recommended as an extra security layer to avoid send your credentials in plain text and instead send them using a base64 encoded string in the Authorization (Basic) header of the request. To use that feature you will need a base64 encoding tool or library to generate your credential's encoded representation from the following format <your-client-id>:<your-client-secret> (notice the colon separating the values).

Assuming the resulting string after applying the base64 function is Y2xpZW50LWlkOmNsaWVudC1zZWNyZXQ=, you request the token in the following format:

curl --request POST 'https://api.khipu.com/token' \
--header 'Authorization: Basic Y2xpZW50LWlkOmNsaWVudC1zZWNyZXQ=' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials'

Response

The requested /token endpoint has a policy to validate all requests against its internal users' database, comparing the submitted credentials with the ones generated for the specified client. If the credentials are valid and the user is active, the access token is returned to the client. If not, a 500 error is returned.

{
    "access_token": "eyJhb...",
    "expires_in": 3600,
    "not-before-policy": 0,
    "refresh_expires_in": 0,
    "scope": "bank-statement",
    "token_type": "Bearer"
}

You need to retrieve the value of the access_token field. Typically you will be using the OAuth JWT scenario inside an application, so it should know how to parse JSON and store the value in a variable.

Please pay attention to the expiration of your token, represented by the expires_in field. "3600" means that this token will be invalid after 3.600 seconds (1 hour). While valid, you can make multiple calls to the API without having to request a new token. The moment the token expires, you will receive 401 error codes and must repeat the process.

API Call

Finally, you use the obtained token to make your call. It is important to precede the value of the token with the word "Bearer" in the Authorization header. See this simplified example:

curl --request GET \
  --url https://api.khipu.com/target-resource \
  --header 'Authorization: Bearer <value of access_token field after calling the /token endpoint>' \
  --header 'Content-type: application/json'