Authorization for Kyriba APIs

Overview

Kyriba API Gateway uses OAuth 2.0 as an API security layer.

OAuth 2.0 protocol is used at the gateway level to support the authorization concerns. It is a well formalized protocol and you can find implementations of it in most of the existing APIs.

Kyriba uses the Client Credentials grant flow. It means that the API gateway validates a pair of client_id / client_secret and responds with an Access token. The application then uses the Access token to call an API.

Creating an Access Token

You can get an Access token to access Kyriba API Playground by using the following endpoint:

POST https://demo.kyriba.com/gateway/oauth/token

Request Parameters

Headers

Body (x-www-form-urlencoded)

Name	Description	Mandatory?
grant_type	The grant type must be client_credentials.
scope	List of required scopes delimited by space. If left empty, the full list of scopes associated with the client_id will be returned.

Postman examples

• Authorization

• Body

cURL example

curl --location 'http://demo.kyriba.com/gateway/oauth/token' --request POST 
  --header 'Authorization: Basic XXX' 
  --header 'Content-Type: application/x-www-form-urlencoded' 
  --data-urlencode 'grant_type=client_credentials'

Response

Status: 200 OK

{
    "access_token": "9ee271ce-6b59-4100-85bb-f9ea6084b4dc",
    "token_type": "bearer",
    "expires_in": 1967,
    "scope": "company-scope"
    "kapp_username": "COMPANY@TEST"
}

Response Parameters

Token Refresh Handling

An access_token is valid for 3600 seconds. All the subsequent calls follow the scenarios presented below:

There are 2 main methods to handle the access_token's life cycle, reduce the number of calls, and improve performance:

1. Store expiry time and request token once expired

Upon receiving a valid access_token, expires_in value, etc., clients can process this by storing an expiration time and checking it on each request. This can be done using the following steps:

• Convert expires_in to an expiry time (epoch, RFC-3339/ISO-8601 date-time, etc.).

• Store the expiry time.

• On each resource request, check the current time against the expiry time and, if the access_token has expired, make a token refresh request before the resource request.

When checking the time, for example, be sure that you are using the same timezone by converting all times to epoch or UTC timezone.

2. Request manually a new token

Another method of handling token refresh is to manually refresh after receiving an invalid token support error.

HTTP Error: 401 Unauthorized

{
    "error": "invalid_token",

    "error_description": "Access token expired: 12345678-399f-47f9-aed7-753366a29569"
}

This can be done with the previous approach or by itself.

If you attempt to use an expired access_token and you get an invalid token error (401), you should perform a new token retrieval.

Using the Access Token in your Requests

Further examples are built on the "Companies" API:

Postman example

cURL example

 curl --location --request GET 'https://demo.kyriba.com/gateway/api/v1/companies \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer dd91afb5-b8b6-4318-853d-2267be82394d'

What Can Be Done with the Kyriba API Playground

The credentials we provide for Kyriba API Playground allow you to interact with our APIs, but with certain restrictions, based on the Access profile that you get. Please mind, PUT (update API items) and DELETE (remove API items) requests are not allowed to perform, in order not to affect the testing experience of other users.

Note❗ Kyriba API Playground provides access exclusively to the API functionality, and not the UI.

Request	Allowed?	Maximum body size:	Maximum file size:
GET (read API items) POST (create API items) PUT (update API items) DELETE (remove API items)		10 MB 10 MB	10 MB 10 MB

Applies to /v1/data/files (Data API).

What Can Be Done with your Own Environment

Request	Allowed?	Maximum body size:	Maximum file size:
GET (read API items) POST (create API items) PUT (update API items) DELETE (remove API items)		10 MB 10 MB	10 MB 10 MB

Applies to /v1/data/files (Data API).

mTLS

Kyriba can optionally use an extra security layer called mTLS. It can be applied on your own environment, therefore if you are interested in using it, please create a Support ticket and check its availability.

TLS stands for Transport Layer Security and is used to secure the connection between the API client and the API server by validating the Kyriba’s server certificate.

mTLS stands for mutual TLS and consists of having the API server also checking the client certificate.

Please refer to the image below for better visualization of the concept: