Authentication

You authenticate with API credentials (apiKey and secretKey) that you generate yourself once Kravata approves your company. You exchange them for a temporary access token and send that token in every request.

Environment	Base URL	Requirements
Test	`https://test-api-kore.kravata.co`	API credentials.
Production	`https://partners-api.kravata.co`	API credentials, mTLS client certificate and IP allowlist.

Get your credentials

Complete the onboarding

In test, register and configure your company yourself with Company sign-up: after your first configuration you receive the credentials link by email, and the credentials page also shows your x-integration-register value. In production, Kravata registers your company during the onboarding and compliance review. You can generate credentials once your company is approved.

Request your credentials link

Open the credentials page of the environment, enter your registered email or your NIT / ID number, and complete the reCAPTCHA.

Environment	Credentials page
Test	`https://test-api-kore.kravata.co/api/v1/client/sandbox/credentials/request`
Production	`https://api-kore.kravata.co/api/v1/client/credentials/request`

Open the link sent to your email

Kravata sends a single-use link to the email registered for your company, never to a different address. The link expires in 15 minutes, and you can request up to 3 links per hour.

Generate and store your credentials

Open the link and click Generate my credentials. Your apiKey and secretKey are shown only once: copy them immediately and store them in a secrets manager.

For security, the page always answers with the same message, whether or not the data matches an approved company. If you don’t receive the email in a few minutes, check that you used the email or ID registered with Kravata, or contact your Kravata point of contact.

For production you also need the mTLS client certificate and private key. Kravata sends them to you directly: request them from your Kravata point of contact. See Production access.

Get an access token

Call Client Login with your credentials.

curl -X POST https://test-api-kore.kravata.co/api/v1/client/token \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "secretKey": "YOUR_SECRET_KEY"
  }'

curl -X POST https://partners-api.kravata.co/api/v1/client/token \
  --cert client.crt --key client.key \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "secretKey": "YOUR_SECRET_KEY"
  }'

The response contains the token (accessToken) and its validity in seconds (expiresIn). Store the token and reuse it until it expires instead of requesting a new one for every call.

Authenticate your requests

Send the token in the Authorization header of every other request:

curl https://partners-api.kravata.co/api/v1/admin/users \
  --cert client.crt --key client.key \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

When the token expires the API responds with 401. Request a new one with the same endpoint.

Production access: mTLS and IP allowlist

For security, the production domain partners-api.kravata.co only accepts connections that present the client certificate issued by Kravata for your company, coming from IP addresses you have registered.

Request your mTLS certificate

Ask your Kravata point of contact for your client certificate (client.crt) and private key (client.key). Store the private key securely: anyone with it and your API credentials can connect as your company.

Present the certificate in every request

Configure your HTTP client to send the certificate and key on every production request, including the token request. Connections without a valid certificate are closed during the TLS handshake, before reaching the API.

Call Update IP Allowlist with the IP ranges of your servers, in CIDR notation. Once a list is registered, requests from any other IP are rejected.

curl -X PUT https://partners-api.kravata.co/api/v1/client/security/ips \
  --cert client.crt --key client.key \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"allowedIpRanges": ["203.0.113.10/32", "198.51.100.0/24"]}'

The list you send replaces the current one. Always include the IP you are calling from: if it is not in the new list, your next requests are rejected, including calls to update the list. Sending an empty list ([]) blocks all IPs. If you lock yourself out, contact Kravata to restore access.

Using the certificate in your HTTP client

import requests

response = requests.post(
    "https://partners-api.kravata.co/api/v1/client/token",
    json={"apiKey": "YOUR_API_KEY", "secretKey": "YOUR_SECRET_KEY"},
    cert=("client.crt", "client.key"),
)

import fs from "node:fs";
import { Agent, fetch } from "undici";

const dispatcher = new Agent({
  connect: {
    cert: fs.readFileSync("client.crt"),
    key: fs.readFileSync("client.key"),
  },
});

const response = await fetch("https://partners-api.kravata.co/api/v1/client/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ apiKey: "YOUR_API_KEY", secretKey: "YOUR_SECRET_KEY" }),
  dispatcher,
});

In Postman, add the certificate in Settings → Certificates → Add certificate for host partners-api.kravata.co.

The interactive playground in this documentation cannot present a client certificate, so use it against the test environment. For production, use your own backend, curl or Postman with the certificate configured.

Call the API only from your backend. Your apiKey, secretKey, certificate private key and access tokens must never reach a browser or a mobile app.

This applies to the Stack API credentials above. The Mobile SDK uses a different value, the sharedKey, which your backend does hand to the app at runtime for each widget session — that is by design and is not the same as your apiKey/secretKey. See Backend for the Mobile SDK.

Guides

API reference

Get your credentials

Get an access token

Authenticate your requests

Production access: mTLS and IP allowlist

Using the certificate in your HTTP client