Connecting to Vayu

To call the Vayu API you need two things from the Vayu app:

• Client id: identifies your organization. Sending it in the x-api-key header is optional today, but we recommend including it on every request.
• API token: a long-lived token you create, with the permissions you choose. You exchange it for a short-lived access token by calling POST /login.

Generate a token

Make your first request

Authentication takes two calls: exchange your API token for an access token, then use the access token on your API calls.

The base URL is https://connect.withvayu.com.

export VAYU_CLIENT_ID="<your client id>"
export VAYU_API_TOKEN="<your API token>"

# 1. Exchange the API token for 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')

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

The /login response looks like this:

{
  "accessToken": "eyJraWQiOi...",
  "expiresIn": 3600,
  "expiresAt": "2026-10-12T11:30:00.000Z"
}

API tokens don't expire on their own. A token keeps working until you revoke it in the Vayu app.

Access tokens last 1 hour. Request a new access token before expiresAt, or when you get a 401 response. Each access token carries the permissions of the API token it came from.

With the Vayu SDK

The SDKs call /login and refresh the access token for you. Pass your API token when you create the client. You don't need to call login() yourself.

npm install vayu-ts

import { Vayu } from 'vayu-ts';

// export CLIENT_ID="<your client id>"
const vayu = new Vayu(process.env.VAYU_API_TOKEN);

const customers = await vayu.customers.list();

import os
from vayu_sdk import Vayu

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

customers = vayu.customers.list()

go get github.com/vayucode/vayu-sdks/go

import (
    "os"

    VayuSDK "github.com/vayucode/vayu-sdks/go"
)

vayu := VayuSDK.NewVayu(os.Getenv("VAYU_API_TOKEN"))

customers, err := vayu.Customers.ListCustomers(nil, nil)

For installation and more examples, see the SDK section.

Permissions

Give each token only the permissions it needs. For example, a service that only sends usage events needs Events → Write and nothing else.

• Read lets the token look up and list records (GET requests).
• Write lets the token create, update, and delete records (POST, PUT, PATCH, and DELETE requests). Write doesn't include Read, so tick both if the token needs both.
• Full access lets the token call every endpoint, including endpoints that aren't listed below.

In the Create API token dialog, the checkbox at the top of the Read or Write column selects that access for every area, and the checkbox on a group row selects it for the whole group.

You can't change a token's permissions after you create it. To change them, create a new token with the right permissions, switch your integration to it, and revoke the old one.

Manage and revoke tokens

The API tokens list in the Vayu API panel shows every token in your account. Each row shows:

• The token name and its permissions, for example Full access or Customers · Read & write.
• The last characters of the token, when it was created, and who created it.
• When it was last used, or Never used.

You can have several active tokens at once. Use a separate token for each integration or environment, so you can revoke one without affecting the others.

To revoke a token:

Rotating a token: create a new token with the same permissions, update your integration to use it, check that it shows a recent Last used time, then revoke the old token.

Troubleshooting

Example of a missing permission:

{
  "type": "permission_error",
  "code": "insufficient_scope",
  "message": "Token lacks required scope vayu.events.write",
  "requiredScope": "vayu.events.write"
}

requiredScope has the form vayu.<area>.<read|write>. For example, vayu.events.write means the token needs Events → Write.

Keep your Client id and API tokens secret. Never put them in client-side code or commit them to source control.