Connecting to Vayu

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.

Scopes

An API Token carries a set of scopes, and any access token you obtain from POST /login inherits them. Every endpoint requires a scope, and a request is only authorized if your token’s scopes cover it.

Scope grammar

A scope takes one of four forms:

Form	Grants
`vayu.<domain>.read`	Read access to one domain
`vayu.<domain>.write`	Write access to one domain
`vayu.<domain>.*`	Both read and write access to one domain
`vayu.*`	Full access — every domain, read and write

Matching is strict. vayu.* covers every request. vayu.<domain>.* covers both read and write on that domain. vayu.<domain>.read covers only read operations on that domain, and vayu.<domain>.write covers only write operations — a write scope does not imply read. Scopes are independent grants, so an ingest-only token can carry vayu.events.write alone, with no read access at all. In the Vayu dashboard, you either leave the “Full access” switch on — the default — or turn it off and tick Read and/or Write per domain: for a single domain, for a whole group (Billing, Catalog, Usage, Other), or for all domains at once. Read and Write are independent ticks and at least one must be ticked; a domain with both ticked is stored as vayu.<domain>.*. vayu.* (full access) is what a token gets when the “Full access” switch is on. Every API Token created before scopes existed also behaves as full access.

Scope domains

Scope domain	Covers	Group
`customers`	Customer records, lookups by external id, name or integration, and customer relations	Billing
`contracts`	Contract creation, listing, lookup, termination, credit refresh, and lookup by integration	Billing
`invoices`	Invoice lookup, listing, and payment status	Billing
`credits`	Credit ledger entries, grants, deductions, and top-ups	Billing
`credit-products`	Listing of credit purchase products	Billing
`plans`	Plan listing, lookup, and deletion	Catalog
`catalog-products`	Catalog product creation, listing, lookup, update, and deletion	Catalog
`custom-fields`	Custom field definition creation, listing, lookup, update, and deletion	Catalog
`events`	Event ingestion and querying, including aggregation and dry-run validation	Usage
`measurements`	Measurement creation, listing, lookup, and deletion	Usage
`meters`	Meter listing, lookup, update, and deletion	Usage
`product-consumptions`	Product consumption lookup by product id	Usage
`cloud-usage-submission`	Submission of cloud marketplace usage records	Usage
`webhooks`	Webhook subscription management	Other

Which scope an endpoint needs

As a rule, GET endpoints need <domain>.read and every other method (POST, PATCH, PUT, DELETE) needs <domain>.write. The one exception is POST /v2/events/aggregation, which needs vayu.events.read since it only queries data. If you generate clients from Vayu’s OpenAPI specification, each operation carries an x-required-scope extension naming the exact scope it needs.

Denied requests

A request whose token lacks the required scope is rejected with a 403 and a permission_error:

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

See Errors for the full error response format.

Changing scopes

Scopes are fixed at creation and can’t be edited on an existing token. To change them, create a new API Token in the Vayu dashboard with the scopes you want, then revoke the old one.

API Documentation

API Reference

Connecting to Vayu

How authentication works

Important Notes

Using Your Credentials

With the Vayu SDK

Direct API Usage

Full example — obtaining and using an access token

Scopes

Scope grammar

Scope domains

Which scope an endpoint needs

Denied requests

Changing scopes

​How authentication works

​Important Notes

​Using Your Credentials

​With the Vayu SDK

​Direct API Usage

​Full example — obtaining and using an access token

​Scopes

​Scope grammar

​Scope domains

​Which scope an endpoint needs

​Denied requests

​Changing scopes

How authentication works

Important Notes

Using Your Credentials

With the Vayu SDK

Direct API Usage

Full example — obtaining and using an access token

Scopes

Scope grammar

Scope domains

Which scope an endpoint needs

Denied requests

Changing scopes