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

Method BaseURL Endpoint Description Example
POST https://demo.kyriba.com/gateway /oauth/token Default value to test
on Kyriba API Playground.
https://demo.kyriba.com/gateway/oauth/token
POST https://{{host}}/gateway /oauth/token Dedicated to test on
Customer environment.
https://opal-sandbox.treasury-factory.com/gateway/oauth/token
https://sapphire.treasury-factory.com/gateway/oauth/token


Headers

Name Description
Authorization Must be Basic. The Basic id contains the client_id:client_secret encoded in base64.
Content-Type Must be application/x-www-form-urlencoded.


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

Parameter Description
access_token This Access token must be used to access the resources.
token_type The Bearer keyword must be used to include the access_token string in the request.
expires_in The lifetime in seconds of the Access token. The expiry being by default 3600 seconds (1 hour).
scope The list of endpoints that the user can access.
kapp_username Identifies which Kyriba Application user the token is linked to. It contains both customer and user codes separated by @.

Token Refresh Handling

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

Token validity Request to the authentication endpoint
Expires in more than 100 seconds Returns the same access_token, including its remaining expiry time.
Expires in less than 100 seconds Returns a new access_token. The previous token remains valid and can be used until it reaches its expiration time.

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

BaseURL Endpoint Description Example
https://demo.kyriba.com/gateway/api /v*/xxxx Default value to test on
Kyriba API Playground.
https://demo.kyriba.com/gateway/api/v1/companies
https://{{host}}/gateway/api /v*/xxxx Dedicated to test on
Customer environment.
https://opal-sandbox.treasury-factory.com/gateway/api/v1/companies
https://sapphire.treasury-factory.com/gateway/api/v1/companies


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 up to: Maximum file size up to:
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 up to: Maximum file size up to: Maximum download limit up to:
GET (read API items)
POST (create API items)
PUT (update API items)
DELETE (remove API items)




10 MB
10 MB

10 MB
10 MB

100 MB
100 MB


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

mTLS

Kyriba can optionally use an extra security layer called mTLS. It can be applied to 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 Kyriba’s server certificate.

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

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