Documentation API

Domains

The KIRI API is designed to facilitate communication between the KIRI platform and its partners. The API allows partners to access user data, generate KiriCoin, and integrate seamlessly with the platform.

Endpoints

• Example of response: { "subscription": true, "timestamp": 1651473012, "last": 245.22, "total": 1893.88, "status": 0 } The subscription key indicates the user's subscription status. The timestamp key indicates the current timestamp in ms. The last key represents the most recent KiriCoin generation for the user. The total key is the current wallet amount.
• NOTE: There are certain situations in which the subscription key could be False:
  • The user decided to disconnect the enabler account with KIRI via kirimarket.com.
  • The user deleted the KIRI account which also triggers the deletion of the connection.
  • There was a problem with the OAuth workflow and the connection does not exist.
• NOTE: If the request is executed but the user identifier {partner_user_id} for the enabler {partner_path} does not exist in the platform, a webhook will be sent by KIRI to notify the enabler about this situation with the default above response.

• Example of request: { "subscription": true, "timestamp": 1651473012, "last": 29.24, "total": 1893.88, "status": 0 } The subscription key indicates the user's subscription status. The last key represents the KiriCoin generated for current request. The total key is the current wallet amount.
• NOTE: There are certain situations in which the subscription key could be False:
  • The user decided to disconnect the enabler account with KIRI via kirimarket.com.
  • The user deleted the KIRI account which also triggers the deletion of the connection.
  • There was a problem with the OAuth workflow and the connection does not exist.
• NOTE: If the request is executed but the user identifier {partner_user_id} for the enabler {partner_path} does not exist in the platform, a webhook will be sent by KIRI to notify the enabler about this situation with the default above response.
• NOTE: During the execution of the request, KIRI sends a webhook with a notification about the change in the total wallet amount to all the enablers connected with the specific user.
• NOTE: If the user is subscribed to any special contest with the enabler inside the KIRI platform, the generation of the KiriCoin from the current request will be taken into consideration for the ranking and possible workflows of the contest.
• NOTE: In the background and through an API interface agreement, the enabler and KIRI must agree to execute certain workflows with the payload provided by the enabler on this endpoint. These workflows must be set up to generate KiriCoin correctly for the specific eco-behaviour, such as driving a Battery Electric Vehicle.
• NOTE: The enabler and KIRI could agree a limitation on the generation of KiriCoin with a specific date of deadline for this limitation. An example is that the user for one specific country is limited to generate up to 10k KiriCoin during a calendar year.
• NOTE: if the query argument ?view=extended is provided in the URL, KIRI can attach certain extended information over the field extended inside the returned payload. This information must be agreed upon in an interface agreement document.

Payload

The payload returned from various endpoints contains information like subscription status, timestamp, event type, and KiriCoin totals.

For every partner, KIRI agrees on a specific payload structure that includes the necessary data for the enabler to process the information correctly.

This data is based on the necessary fields to calculate the right KIRI Coin generation for the user based on the eco-behaviour and the specific workflows agreed between the enabler and KIRI.

HTTP Responses

HTTP responses include various statuses that indicate if a request was successful or failed.

• Example of response: { "message": "Bad headers or request malformed!", "status": 1 }

• Different kind of responses:
  • 200 OK: The request was successful.
  • 400 Bad Request: Malformed request, invalid headers or rate limit reached.
  • 401 Unauthorized: Invalid or missing authentication.
  • 404 Not Found: Resource not found.
  • 422 Unprocessable Entity: Invalid request parameters.

Webhooks

Webhooks are used to notify updates in real-time, ensuring seamless synchronization between the enabler and KIRI. For example, when a user updates their profile or makes changes to their KiriCoin balance, a webhook is sent to the designated endpoint.

Events

Triggered webhook events allow keeping track of account activities, including user creation, updates, or account linking.

• Different kind of events:
  • user.create: Triggered when a new user is created.
  • user.delete: Sent when a user account is deleted.
  • user.link: Triggered when a user links their account with an enabler.
  • user.unlink: Sent when a user unlinks their account from Marketplace.
  • coins.update: Triggered whenever there is a change in a user's KiriCoin balance.
  • coins.generate: Sent when KiriCoin is generated for a user.
  • partner.zeroing: Triggered when a partner's KiriCoin balance is reset to zero. In this case, KIRI acts as a job scheduler.
• NOTE: For the events user.create, user.link, coins.update and coins.generate Kiri can add a bonus on top for each event executed. An example would be that each user created on the platform receives 10KC for signing up.
• NOTE: Sending webhooks over HTTPS provides a secure channel for transmitting data between two systems. To further enhance security and prevent MITM attacks, Kiri highly recommends using Mutual TLS (MTLS) for webhook communication. With MTLS, both the client and server must present valid and trusted certificates to each other, ensuring that the data is not intercepted or tampered with during transmission.
• NOTE: Implementing MTLS can add an extra layer of protection to the webhook infrastructure, making it less vulnerable to attacks and unauthorised access. Basic Auth can also be used to require a username and password to access the webhook endpoint, adding an extra layer of security to the transmission of webhook data. By using these security techniques, Kiri can ensure that webhook data is transmitted securely and is only accessible by authorised parties.
• NOTE: Basic Auth can also be used to require a username and password to access the webhook endpoint, adding an extra layer of security to the transmission of webhook data. By using these security techniques, Kiri can ensure that webhook data is transmitted securely and is only accessible by authorised parties.
• NOTE: KIRI and the enabler can agree in an interface agreement document on the configuration and how to connect with the webhook. This ensures that Kiri and the enabler are aligned on all communication and send the proper events as they occur.

Security Aspects

Security aspects involve using techniques such as HMAC and timestamping to ensure safe communication. All requests must be authenticated and authorized, and a rate limit is imposed to prevent abuse.

All requests to the platform must be authenticated and duly authorized, except those related to "Pre-Sale Application" that must be agreed between the enabler and KIRI. In addition, depending on each endpoint, a rate-limit will be imposed to prevent possible DDOS attacks or abuse of the API by external attackers.

If the integration is a M2M integration and the requests are not coming from a mobile application, the IP will be the same for each request so it will be blocked automatically because of the rate-limit. To bypass this situation, we have provided a special header to allow this kind of communication.

• NOTE: All requests generating a write operation on KIRI platform like PUT, POST or PATCH should provide the hashed payload within the original payload based on the HMAC security technique. KIRI must provide the SHA Key for staging and production environments before any testing or communication. Otherwise, all the requests will be rejected for this reason.
• NOTE: All requests to the platform must include a special header with the current timestamp based on Timestamping security technique. All the requests without this header or with a value greater than the configured on the KIRI platform will be rejected for this reason.
• NOTE: All requests to the platform must include the custom Enabler Key facilitated by KIRI in an API interface agreement. This Provider Key will match and be unique to the rest of the enablers of the platform. This could vary for the different environments, depending on the needs of the enabler.

• International standards followed:
  • General Data Protection Regulation 2016/679 (GDPR)
  • ISO/IEC 9001: Quality Management System
  • ISO/IEC 9126: Software Product Quality Measurement
  • ISO/IEC 12207: Software Life Cycle Processes
  • ISO/IEC 27002: Information Technology – Security Techniques
  • ISO/IEC 27034: Application Security Guidelines
  • NIST Cybersecurity Framework
  • OWASP Application Security Verification Standard (ASVS) 4.0.3
  • OWASP Dependency-Check
  • OWASP Software Assurance Maturity Model (SAMM)

HMAC

Hash-based Message Authentication Code (HMAC) is used to authenticate data transmissions to prevent MITM attacks. HMAC ensures the integrity and authenticity of a message by generating a unique code based on the data and a secret key.

Timestamping

It ensures that requests are recent and not replayed from an earlier time. Each request must include a Unix timestamp in the headers, and requests older than one minute are automatically rejected.