Vayu Docs

To connect to Vayu and get your API credentials, follow these steps:

Log into Vayu at http://app.withvayu.com
Navigate to the Integrations section
Click "Connect" on the Vayu card

A side pane will open with two important fields:

Client ID - Identifies your organization on every request (x-api-key header)
API Token - A long-lived token used to obtain short-lived access tokens via the /login endpoint

Copy the API Token immediately — it won't be shown again after you close the pane.

How authentication works

Vayu uses a two-token model:

Token	Where it comes from	Lifetime	How it's used
API Token (refresh token)	Vayu dashboard	Long-lived	Sent to `POST /login` to get an access token
Access token	`POST /login` response	1 hour	Sent as `Authorization: Bearer <token>` on every API call

The SDKs handle this exchange automatically — pass your API Token when initializing the client and the SDK calls /login and refreshes the access token as needed.

Important Notes

You can only have one active API Token at a time
To rotate your API Token: revoke the existing one, then generate a new one from the same place

Using Your Credentials

With the Vayu SDK

The SDKs handle the full token lifecycle — just pass your API key and start making calls.

import { Vayu } from 'vayu-ts';

const vayu = new Vayu(process.env.VAYU_API_KEY);

// Start using the client — authentication is automatic
const customers = await vayu.customers.list();

from vayu_sdk import Vayu

vayu = Vayu(api_key=os.environ["VAYU_API_KEY"])

# Start using the client — authentication is automatic
customers = vayu.customers.list()

import vayu "github.com/vayucode/vayu-sdks/go"

v := vayu.NewVayu(os.Getenv("VAYU_API_KEY"))

// Start using the client — authentication is automatic
customers, err := v.Customers.List()

# Step 1 — Get an access token
ACCESS_TOKEN=$(curl -s -X POST "https://connect.withvayu.com/login" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VAYU_CLIENT_ID" \
  -d "{\"refreshToken\": \"$VAYU_API_TOKEN\"}" | jq -r '.accessToken')

# Step 2 — Make API calls with the token
curl "https://connect.withvayu.com/customers" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-api-key: $VAYU_CLIENT_ID"

For installation and more examples, see the SDK section.

Direct API Usage

Every request needs two headers:

x-api-key: <your Client ID>
Authorization: Bearer <access token> (obtained from POST /login)

Make sure to keep your Client ID and API Token secure and never expose them in client-side code.

Full example — obtaining and using an access token

# Step 1 — Exchange your API Token for a short-lived access token
ACCESS_TOKEN=$(curl -s -X POST "https://connect.withvayu.com/login" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VAYU_CLIENT_ID" \
  -d "{\"refreshToken\": \"$VAYU_API_TOKEN\"}" | jq -r '.accessToken')

# Step 2 — Use the access token on subsequent requests
curl "https://connect.withvayu.com/customers" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "x-api-key: $VAYU_CLIENT_ID"

// Without the SDK — manual token exchange with fetch
const loginRes = await fetch("https://connect.withvayu.com/login", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.VAYU_CLIENT_ID,
  },
  body: JSON.stringify({ refreshToken: process.env.VAYU_API_TOKEN }),
});
const { accessToken } = await loginRes.json();

const customersRes = await fetch("https://connect.withvayu.com/customers", {
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "x-api-key": process.env.VAYU_CLIENT_ID,
  },
});
const customers = await customersRes.json();

# Without the SDK — manual token exchange with requests
import os, requests

login = requests.post(
    "https://connect.withvayu.com/login",
    headers={"x-api-key": os.environ["VAYU_CLIENT_ID"]},
    json={"refreshToken": os.environ["VAYU_API_TOKEN"]},
)
access_token = login.json()["accessToken"]

customers = requests.get(
    "https://connect.withvayu.com/customers",
    headers={
        "Authorization": f"Bearer {access_token}",
        "x-api-key": os.environ["VAYU_CLIENT_ID"],
    },
).json()

// Without the SDK — manual token exchange with net/http
loginBody, _ := json.Marshal(map[string]string{
    "refreshToken": os.Getenv("VAYU_API_TOKEN"),
})
req, _ := http.NewRequest("POST", "https://connect.withvayu.com/login",
    bytes.NewBuffer(loginBody))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-api-key", os.Getenv("VAYU_CLIENT_ID"))

resp, _ := http.DefaultClient.Do(req)
var loginRes struct{ AccessToken string `json:"accessToken"` }
json.NewDecoder(resp.Body).Decode(&loginRes)

req, _ = http.NewRequest("GET", "https://connect.withvayu.com/customers", nil)
req.Header.Set("Authorization", "Bearer "+loginRes.AccessToken)
req.Header.Set("x-api-key", os.Getenv("VAYU_CLIENT_ID"))

resp, _ = http.DefaultClient.Do(req)

Access tokens expire after 1 hour. If using a raw HTTP client, re-call /login when you receive a 401 response. The SDKs handle this automatically.

Connecting to Vayu