Getting Your API Key and Secret

To authenticate with Visla OpenAPI, you need a key and secret, which can be obtained from the Visla app under Workspace Settings. Follow these steps:

Navigate to Workspace Settings
1. In the Visla app, go to Workspace Settings.
Go to the API Tab
1. Click on the API tab to manage your API credentials.
Generate Your Key and Secret
1. If you haven’t created one yet, generate a new key and secret.
2. The key and secret are only visible to the creator.
Important Notes:
1. The full key and secret can only be seen once at the time of creation. There is no way to view them again later.
2. Each member in a workspace can create only one key and secret at a time.
3. You can refresh your key and secret, but this will invalidate the old credentials.
4. Keys do not expire unless manually refreshed.

Make sure to securely store your key and secret during creation, as they cannot be retrieved later.

How to Use Your API Key and Secret

To make authenticated requests to the Visla OpenAPI, you need to generate an encrypted signature using the key and secret.

Generate the Signature
Using the key and secret provided, generate an encrypted signature. The signature is created using a hashing algorithm (e.g., HMAC-SHA256) and includes the request details, ensuring the request is secure and authentic.
Include the Signature in the Request
Add the generated signature to the HTTP headers for all Visla OpenAPI requests.

📘
The HTTP method used to generate the encrypted signature must be in all uppercase (e.g., GET, POST), and the full URL must be included.

A detailed example is provided below to guide you through the process.

import time
import uuid
import hmac
import hashlib
from datetime import datetime

OPENAPI_CREDENTIALS = {
    "key": "",
    "secret": ""
}

def sign_openapi_headers(method, url):
    SIGN_STRING_PATTERN = "{method}|{url}|{ts}|{nonce}"
    ts = int(round(time.time() * 1000))
    nonce = uuid.uuid4()
    to_sign = SIGN_STRING_PATTERN.format(method=method.upper(), url=url, ts=ts, nonce=nonce);
    signed = hmac.new(bytes(OPENAPI_CREDENTIALS["secret"],'utf-8'), bytes(to_sign, 'utf-8'), hashlib.sha256).hexdigest()

    api_headers = {"Content-Type": "application/json; charset=utf-8", "key":  OPENAPI_CREDENTIALS["key"], "ts": f'{ts}', "nonce": str(nonce), "sign": f'{signed}'}
    return api_headers

const crypto = require('crypto');
const uuid = require('uuid');

const OPENAPI_CREDENTIALS = {
    key: "",
    secret: ""
};

const signOpenApiHeaders = (method, url) => {
    const SIGN_STRING_PATTERN = "{method}|{url}|{ts}|{nonce}";
    const ts = Date.now();
    const nonce = uuid.v4();
    const toSign = SIGN_STRING_PATTERN
        .replace("{method}", method.toUpperCase())
        .replace("{url}", url)
        .replace("{ts}", ts)
        .replace("{nonce}", nonce);

    const signed = crypto
        .createHmac('sha256', OPENAPI_CREDENTIALS.secret)
        .update(toSign)
        .digest('hex');

    return {
        "Content-Type": "application/json; charset=utf-8",
        "key": OPENAPI_CREDENTIALS.key,
        "ts": ts.toString(),
        "nonce": nonce,
        "sign": signed
    };
};

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.SignatureException;
import java.util.UUID;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class OpenApiAuth {
    private static final String SECRET_KEY = "";
    private static final String API_KEY = "";

    public static Map<String, String> signOpenApiHeaders(String method, String url) throws Exception {
        final String SIGN_STRING_PATTERN = "{method}|{url}|{ts}|{nonce}";
        long ts = System.currentTimeMillis();
        String nonce = UUID.randomUUID().toString();
        
        String toSign = SIGN_STRING_PATTERN
                .replace("{method}", method.toUpperCase())
                .replace("{url}", url)
                .replace("{ts}", String.valueOf(ts))
                .replace("{nonce}", nonce);

        String signed = hmacSha256(toSign, SECRET_KEY);

        Map<String, String> apiHeaders = new HashMap<>();
        apiHeaders.put("Content-Type", "application/json; charset=utf-8");
        apiHeaders.put("key", API_KEY);
        apiHeaders.put("ts", String.valueOf(ts));
        apiHeaders.put("nonce", nonce);
        apiHeaders.put("sign", signed);

        return apiHeaders;
    }

    private static String hmacSha256(String data, String key) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKeySpec = new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        mac.init(secretKeySpec);
        byte[] hmacBytes = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
        StringBuilder hexString = new StringBuilder();
        for (byte b : hmacBytes) {
            String hex = Integer.toHexString(0xff & b);
            if (hex.length() == 1) {
                hexString.append('0');
            }
            hexString.append(hex);
        }
        return hexString.toString();
    }
}