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 (JWT format) 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.

🔐 OAuth token

OAuth 2.0 is an industry-standard protocol for authorization, enabling applications to obtain limited access to user accounts on an HTTP service. It provides a secure and scalable method for obtaining user authorization while protecting user credentials. We use JSON Web Tokens (JWT) to securely transmit information between parties, ensuring that the data can be verified and trusted. JWT is a compact, URL-safe means of representing claims between two parties, typically consisting of a header, payload, and signature. It is commonly used in OAuth scenarios due to its ability to be easily verified and its support for self-contained, tamper-proof claims. Also, it can be easily revoked, if it has been compromised.

OAuth flows

Two-Legged (Client Credentials Flow)

The two-legged approach, also known as the client credentials flow, is used for server-to-server interactions where the application accesses resources on its own behalf without user involvement. In the case of Khipu's Open Data APIs, it will be used to access public data sources.

Three-Legged (Authorization Code Flow)

The three-legged approach, or authorization code flow, involves user consent and is used when an application needs to access resources on behalf of a user. In this flow, the client application redirects the user to the authorization server for consent. The graphical interface will be similar to that of a normal payment in Khipu, but upon completion of the process the redirection will immediately occur to the redirect_uri callback specified when starting the authentication.

It is the responsibility of the client to implement the redirect URI to receive the authorization code after the user's consent.

We've implemented this flow using the OpenId Connect protocol, so, if needed, we can include user's information in claims inside an id_token.

Obtaining JWT Using Client Credentials Flow

To obtain a JWT using the client credentials flow, follow these steps:

Requesting a Token

curl -X POST https://auth-server.khipu.com/oauth2/token \
  -H "Authorization: Basic $(echo -n 'client_id:client_secret' | base64)" \
  -d "grant_type=client_credentials"

• grant_type : The type of grant being used. For this flow, it is client_credentials .
• Authorization : Basic authentication header containing the client ID and client secret, base64-encoded.

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR...",
  "token_type": "bearer",
  "expires_in": 31536000,
  "scope": "openid"
}

• access_token : The JWT to be used for accessing protected resources.
• token_type : The type of token ("bearer").
• expires_in : The validity period of the token in seconds.
• scope : The scopes granted to the token.

Obtaining JWT Using Authorization Code Flow

To obtain a JWT using the authorization code flow, follow these steps:

Step 1: Redirecting User for Consent

Redirect the user to the authorization server:

https://auth-server.khipu.com/oauth2/authorize
?client_id=<your_client_id>
&redirect_uri=https://your-app.com/callback
&response_type=code
&response_mode=query
&scope=openid
&state=<random_string>
&nonce=<random_string>
&custom=<optional_value>
&institution_id=<institution_for_consent_process>

• client_id : The client ID of your application.
• redirect_uri : The URI where the authorization code will be sent after user consent.
• response_type : The type of response. For this flow, it is "code".
• response_mode : Choose how you want to receive the authorization code on your redirect_uri . It can be query or form_post .
• scope : The permissions your application is requesting. For Khipu's API, use always openid api (two scopes separated by a whitespace).
• state and nonce are optional values, but recommended for increased security. If you send nonce it will be returned as a claim in the JWT.
• custom : you can use this field to send a value that you want to associate with the JWT (it will be added as a claim). For example, you can set its value to indicate a unit or department on your company where the JWT will be used. This value will be returned in the response in the x-custom header.
• institution_id : Please refer to the list of institutions we currently support. You must include a valid institution so the consent process can start.

Step 2: Exchanging Authorization Code for Token

After the user consents, the authorization server redirects to the specified redirect URI with an authorization code. Use this code to request a token:

curl -X POST https://auth-server.khipu.com/oauth2/token \
  -H "Authorization: Basic $(echo -n 'client_id:client_secret' | base64)" \
  -d "grant_type=authorization_code" \
  -d "code=<authorization_code_received>" \
  -d "redirect_uri=https://your-app.com/callback"

• grant_type : The type of grant being used. For this flow, it is authorization_code .
• code : The authorization code received from the authorization server.
• redirect_uri : The same URI used during the authorization request.

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR...",
  "token_type": "bearer",
  "expires_in": 31536000,
  "id_token": "tGzv3JOkF0XG5Qx2TlKWIA...",
  "scope": "openid"
}

• id_token : In the first phase of OAuth implementation, it will not include user's data, only basic standard claims such as: sub , aud , iss .

Where to find your client credentials

To authenticate against our /token endpoint (and also /revoke), you must send credentials that can be obtained in your private page in khipu.com. Go to your account settings ("Opciones de la cuenta") and scroll down until you find the values in the section "Para integrar Khipu a tu sitio web", as shown below.

• client_id : Will be the value of the "Id de cobrador" field.
• client_secret : Will be the value of the "Llave" field.

Using the JWT to Access Protected Resources

To access protected resources using the obtained JWT, include it in the Authorization header of your request:

curl -X POST https://api.khipu.com/resource \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR..."
  <payload>

Please refer to the "Open Data API" section in this site to view the documentation and examples for each available endpoint.

About token expiration and other features

The JWT tokens issued by our authorization servers will be valid for a full year. The possibility to use refresh tokens is disabled. If a token becomes compromised, you can revoke it and generate a new one. After each credential change (for example, when a bank forces its client to change password), the current JWT must not be used anymore, and the user must go through the authentication flow again.

Revoking a JWT

To revoke a JWT and put it on a blacklist, use the following endpoint:

curl -X POST https://auth-server.khipu.com/oauth2/revoke \
  -H "Authorization: Basic $(echo -n 'client_id:client_secret' | base64)" \
  -d "token=eyJhbGciOiJIUzI1NiIsInR..."

• token : the JWT bearer token you wish to revoke.

You should get a HTTP 200 status code to indicate the token was revoked.

PKCE support

Our authentication server supports Proof Key for Code Exchange (PKCE), an extension to the OAuth 2.0 Authorization Code Flow designed to enhance security for public clients, such as mobile or single-page applications. PKCE mitigates the risk of authorization code interception by requiring the client to generate a random secret, known as a code verifier, before initiating the authorization request. The client then hashes this code verifier (using SHA-256 for instance) to create a code challenge, which is sent to the authorization server along with the authorization request. Upon receiving the authorization code, the client must send the original code verifier to the /token endpoint. The server verifies the code challenge against the code verifier before issuing the access token. To use PKCE in the Authorization Code Flow, ensure your client generates a code verifier, creates a code challenge, and includes the code challenge in the initial authorization request (using the code_challenge and code_challenge_method parameters). The code verifier (code_verifier parameter) must then be sent when exchanging the authorization code for an access token.

Errors in the authorization code flow

If an error occurs during the authentication flow regarding parameters sent to the /authorization endpoint, the user's browser will be redirected to the value passed in the redirect_uri parameter (provided it exists and is valid) with details about the error in the query string parameters. Your backend server can detect the existence of these parameters to make appropriate corrections or provide better information to the user. This is the structure of the error parameters:

• error_code : Internal code to classify the error. See the table below.
• error_type : Category associated with the error code. Indicates whether it is possible to restart the flow or if some adjustment must be made to the request.
• error_description : Descriptive message about the error.
• state : Value of the state parameter, provided it was sent in the original request.

🔑 Api key

The API key is the simplest approach, as all you need to do is pass your account's unique key as a parameter in a special HTTP request header called x-api-key.

This value is initially provided to you when you activate your Khipu account, so it is your responsibility to save your key and keep it safe at all times, being careful not to share it with unwanted users or commit it to your source repository.

API Call

An example 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'
  --data-raw '{
    "RequestData": {
      <payload>
    }
  }'