API Authentication

In this section, we will discuss how to authenticate to our Venly API products which contain the Wallet, NFT and PAY-API.

📘
Venly uses OAuth + JWT authorization for its APIs.

Authentication Flow Diagram

Authentication Steps

To authenticate calls for API products, follow these steps:

1. Obtain Access Credentials

Get your Client ID and Client Secret from the authentication section of the Developer Portal.

🚧
There are two types of access credentials:

Sandbox Credentials (For the sandbox environment to test with testnets)

Production Credentials (For the production environment for deploying on mainnet)

You can switch between the access credentials from the authentication page by hitting the toggle button.

2. Request Access Token

Make a POST request to the authentication endpoint with your client credentials to get an access_token (bearer token).

📘
Use sandbox credentials with the sandbox endpoint and production credentials with the prodution endpoint.

Sandbox Environment Endpoint (Runs on testnet chains and is used for trying out or testing purposes):

POST https://login-sandbox.venly.io/auth/realms/Arkane/protocol/openid-connect/token

Production Environment Endpoint (Runs on mainnet chains and used for real API calls):

POST https://login.venly.io/auth/realms/Arkane/protocol/openid-connect/token

Request Body:

{
    "grant_type": "client_credentials", //this will be "client_credentials"
    "client_id": "<your_client_id>",
    "client_secret": "<your_client_secret>"
}

Name	Type	Description
`grant_type`	string	This will be `client_credentials`
`client_id`	string	Client ID provided to you by Developer Portal.
`client_secret`	string	Client Secret provided to you by Developer Portal.

Response Body

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmQi1UenBOb0hBVGhwT2J4aW9qTDBrdm83MldmRzRXRXh1eFpiaXlGQUhzIn0.eyJleHAiOjE3Mjc5NDc5MTYsImlhdCI6MTcyNzk0NzU1NiwianRpIjoiNmY0OWQ0MWMtZWFlZi00MzMyLTlhMDAtOTU2M2VkMzMyZmMyIiwiaXNzIjoiaHR0cHM6Ly9sb2dpbi1zYW5kYm94LnZlbmx5LmlvL2F1dGgvcmVhbG1zL0Fya2FuZSIsImF1ZCI6WyJBcmthbmVNYXJrZXQiLCJXYWxsZXQtQVBJIiwicmVhbG0tbWFuYWdlbWVudCIsIk5GVC1BUEkiLCJQYXkiLCJOb3RpZmljYXRpb25zIl0sInN1YiI6IjE2ZjJkMGNiLTBmNDUtNDFlNS1hOGFlLWY3MTcyZWRlMjQ1YyIsInR5cCI6IkJlYXJlciIsImF6cCI6IjQ3YjE4ZDdmLWI4YzktNGIyYy1hM2ZmLTg2OTE2OTljMDhjOCIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJQYXkgQVBJIiwiTWFya2V0IEFQSSIsIk5GVC1BUEkiLCJwcm9mZXNzaW9uYWwtYnAtYXBpIiwiV2FsbGV0IEFQSSJdfSwicmVzb3VyY2VfYWNjZXNzIjp7IkFya2FuZU1hcmtldCI6eyJyb2xlcyI6WyJjcmVhdGU6c3ViLXVzZXIiLCJjcmVhdGU6YXVjdGlvbiIsImJ1eTpzYWxlIiwiY3JlYXRlOmJpZCIsImNyZWF0ZTpzYWxlIiwiY3JlYXRlOnN1YnVzZXItYWRkcmVzcyJdfSwiV2FsbGV0LUFQSSI6eyJyb2xlcyI6WyJmaWx0ZXI6bnNmdyIsImZpbHRlcjpzcGFtIiwidXNlOnN3YXBzIiwidmlldzphcmNoaXZlZC13YWxsZXRzIiwic2F2ZTp0cmFuc2FjdGlvbiIsIndoaXRlbGFiZWwiLCJzaWduOndhbGxldHMiLCJzYXZlOnNpZ25hdHVyZSJdfSwicmVhbG0tbWFuYWdlbWVudCI6eyJyb2xlcyI6WyJxdWVyeS1jbGllbnRzIiwicXVlcnktZ3JvdXBzIl19LCJORlQtQVBJIjp7InJvbGVzIjpbInVzZTpjbG91ZC1zdG9yYWdlIiwidXNlOmN1c3RvbS1zdG9yYWdlIiwidmlldzpjb250cmFjdHMiLCJ2aWV3Om1pbnRlci13YWxsZXQiLCJtYW5hZ2U6dG9rZW4tdHlwZXMiLCJ1c2U6aXBmcy1zdG9yYWdlIiwibWludDp0b2tlbnMiLCJ2aWV3OmVudmlyb25tZW50cyIsImNyZWF0ZTptaW50ZXItd2FsbGV0IiwiY3JlYXRlOmNvbXBhbnktbWludGVyLXdhbGxldCIsIm1hbmFnZTptaW50ZXItd2FsbGV0Iiwidmlldzp0b2tlbi10eXBlcyIsIm1hbmFnZTphcHBzIiwidmlldzp0b2tlbnMiLCJtYW5hZ2U6dG9rZW5zIiwidmlldzppdGVtcyIsIm1hbmFnZTpjb250cmFjdHMiLCJ1cGxvYWQ6bWVkaWEiXX0sIlBheSI6eyJyb2xlcyI6WyJjcmVhdGU6Y2hlY2tvdXQtc2Vzc2lvbiIsInJldHJpZXZlOmNoZWNrb3V0LXNlc3Npb24iXX0sIk5vdGlmaWNhdGlvbnMiOnsicm9sZXMiOlsibWFuYWdlOndlYmhvb2tzIl19fSwic2NvcGUiOiJ2aWV3OndhbGxldC1hbmFseXRpY3Mgc2F2ZTpzaWduYXR1cmUgd2hpdGVsYWJlbCBzaWduOndhbGxldHMgdmlldzphcmNoaXZlZC13YWxsZXRzIHNhdmU6dHJhbnNhY3Rpb24iLCJjb21wYW5pZXMiOlt7ImlkIjoiYmZmOTMzNzEtZGI0MC00MzYzLTk2OTItNGZiZTY0YTM0YjU0IiwibmFtZSI6IlZlbmx5In1dLCJjbGllbnRIb3N0IjoiNTguNjUuMjIwLjIxNSIsImNsaWVudElkIjoiNDdiMThkN2YtYjhjOS00YjJjLWEzZmYtODY5MTY5OWMwOGM4IiwiY2xpZW50QWRkcmVzcyI6IjU4LjY1LjIyMC4yMTUifQ.c5Xlk-Yz0BatmCnvnhhBY_7yzqUglNDGwr2GTT1t5QILKza9HooXlqnKo-dxiYNKB1yN7COLc_TZtnr58g6AwKbezFdOW95_Ac-Qe2WysSxK8JQvfcn6CSzEOLNx-YHoernWdkX-_PoKmEfm0XjhFzUXcPT4MLA3GZGpPCJQbzNZQU8-WLUGyWCjyjibPQ_FimGJaLpHh5gDtWKv5y5GXz-7cTfLtb_rUly9gy2a0zNOkDlN4FHBOINE9fW0OaSNbCrPmzC0aJf_BUJ2AmUwk7rzfd9i3hkz2zCKH8iwHHoL1OisKwCg2ExDngr1WLhTQLm-vCJBvkAtA3jLoP2XTg",
    "expires_in": 360,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 1572970662,
    "scope": "view:wallet-analytics save:signature whitelabel sign:wallets view:archived-wallets save:transaction"
}

3. Use Access Token

Include the access_token in the Authorization header of your API requests as a Bearer token.

Authorization: Bearer <your_access_token>

4. Refresh Token (when needed)

The access token is valid for 6 minutes. After 6 minutes, you will need to request a new access token. This can be done by performing the same call.

📘
The refresh_token is provided but is deprecated and should not be used to receive a new access_token. Use the same method to request a new access token instead.

The expiration is in the token itself, so it would be better to read the expiry and only fetch a new token if it is expired.

For example in javascript, this can be done with the help of jwt-decode and the following code:

import jwtDecode from 'jwt-decode';

const isTokenExpired = (token) => {
  if (!token) return true;
  try {
    const decodedToken = jwtDecode(token);
    const currentTime = Date.now() / 1000;
    return decodedToken.exp < currentTime;
  } catch (error) {
    console.error('Error decoding token:', error);
    return true;
  }
};

Using the Bearer token in the API calls

In the result of the previous call, an access_token is returned. This access_token must be passed with every API call you do (as a Bearer token in the authorization header).

To run API calls on our documentation tool, you can enter the access_token as shown below to authenticate calls:

Entering Bearer Token to Authenticate API Calls

Video Guide

👍
Learn more about our different APIs, Wallet-API, NFT-API and PAY-API

API Security, best practices

Authentication is a critical aspect of securing access to resources. Following best practices and using secure authentication methods can protect your system and its data from unauthorized access. To learn more about best security practices for API security, please refer to the guide below.

📘
Learn more about the best practices for API security.