Konvert API

The Konvert API is a GraphQL API which allows access to portal data for any external system or custom development needs.


Endpoints

All requests are completed over the same endpoint using POST.


Production API: https://api.konvertapp.com/api

Staging API: https://api.staging.konvertapp.com/api

The staging environment can have different data and configuration than production. Not all portal clients are setup on staging automatically. Do not use this environment unless you are instructed to do so.

If you have a need for a Konvert staging environment, please reach out to support.


API Explorer and Documentation

The Konvert API field documentation can be viewed from the Konvert API Explorer at https://api-explorer.konvertapp.com/

If you have a Konvert API key and secret, you can enter it to run live queries and mutations and help assist in your development process.


Operation Collections

Common queries and mutations can be viewed by clicking on the Operation Collections tab icon in the sidebar of the API Explorer:


API Mode

When accessed with a API key and secret, the API is accessed as a service connection not specific to any single user. Access using a key and secret can be used to access and / or modify portal data, but cannot operate as if a single user is logged into a portal performing actions for themself.


Authentication

There are 2 different options to authenticate with the Konvert API:

  1. OAuth 2.0 Client Credentials Grant / Flow
  2. JSON Web Token (JWT)

In both methods it is important to protect your Konvert API secret key and only use it from a secure server side area.


OAuth 2.0 Client Credentials Grant / Flow

reference: https://datatracker.ietf.org/doc/html/rfc6749#section-4.4

The client credentials grant type MUST only be used by confidential
clients.

     +---------+                                  +---------------+
     |         |                                  |               |
     |         |>--(A)- Client Authentication --->| Authorization |
     | Client  |                                  |     Server    |
     |         |<--(B)---- Access Token ---------<|               |
     |         |                                  |               |
     +---------+                                  +---------------+

   The flow illustrated includes the following steps:

   (A)  The client authenticates with the authorization server and
        requests an access token from the token endpoint.

   (B)  The authorization server authenticates the client, and if valid,
        issues an access token.

OAuth 2.0 Token Endpoints:

Production API: https://api.konvertapp.com/oauth/token

Staging API: https://api.staging.konvertapp.com/oauth/token

These OAuth 2.0 endpoints only support the Client Credentials grant, if you are looking to implement SSO for an external application for users logging in with their portal credentials, please reach out to support.

In order to execute this flow, your application will send a POST request with the Authorization header that contains the word Basic  followed by a space and a base64-encoded string client_id:client_secret .

Content-Type header must be application/x-www-form-urlencoded and the Body must be grant_type=client_credentials


Request Example

POST https://api.konvertapp.com/oauth/token
Authorization: Basic eW91ckFwaUtleTp5b3VyQXBpU2VjcmV0MTIzNDU2Nzg5MA==
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Response Example

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ5b3VyQXBpS2V5IiwiaWF0IjoxNzQ2ODE4NzIyLCJleHAiOjE3NDY4MjA1MjJ9.TH_eykUrFVHxKCmjzu-KUviJLcwnIKxd5bWA86d6Y7g",
    "token_type": "Bearer",
    "expires_in": 21600
}

Once you have an access token, provide it as a Bearer token in the Authentication header to all calls to the Konvert API.

Authorization = Bearer [token]



JSON Web Token (JWT)

reference: https://datatracker.ietf.org/doc/html/rfc7519


As an alternative to using the Oauth 2.0 Client Credentials flow, you can generate an access token by signing a JSON Web Token.

The API key and secret can be used to generate a JWT which can be used to authenticate with the Konvert API.


Use a JWT library (https://jwt.io/) to generate the access oken using the API key as the Subject (sub) and the secret key as the private key to sign the payload with.


Example: 

// this example uses the Node library jsonwebtoken
const token = jwt.sign(
  {sub: apiKey},
  apiSecretKey,
  { expiresIn: 3600, algorithm: "HS256" }
);

expiresIn is the number of seconds the token should be valid for. Must not be greater than 6 hours (21600 seconds).


Once you have an access token, provide it as a Bearer token in the Authentication header to all calls to the Konvert API.

Authorization = Bearer [token]