Getting started / Authentication

Authentication

Access to these APIs is secured with OAuth 2.0. An edition-scoped API key may accompany the access token.

OAuth 2.0

Use this authorization code flow method for secure, token-based access.

Learn more ↗

API Key

Include the API Key in the request header as x-vani-apikey to authorize access to resources.

Header: x-vani-apikey

OAuth 2.0 flow

Vani uses the standard OAuth 2.0 authorization code flow through Zoho Accounts.

Register your applicationGet your client ID and secret from the Zoho API Console.
Redirect the user to the authorization URLThe user grants the scopes you request.
Exchange the authorization codeReceive an access token and a refresh token.
Make API requestsSend the access token in the Authorization header.
Refresh tokensUse the refresh token to mint new access tokens.

Endpoints

Authorisation is served by Zoho Accounts, not by the API host. Use the row for your edition's data centre — an OAuth client is valid only in the data centre it was registered in.

Data centre	Authorization endpoint	Token endpoint
.com default	https://accounts.zoho.com/oauth/v2/auth	https://accounts.zoho.com/oauth/v2/token
.in	https://accounts.zoho.in/oauth/v2/auth	https://accounts.zoho.in/oauth/v2/token
.eu	https://accounts.zoho.eu/oauth/v2/auth	https://accounts.zoho.eu/oauth/v2/token
.ca	https://accounts.zohocloud.ca/oauth/v2/auth	https://accounts.zohocloud.ca/oauth/v2/token
.com.au	https://accounts.zoho.com.au/oauth/v2/auth	https://accounts.zoho.com.au/oauth/v2/token
.sa	https://accounts.zoho.sa/oauth/v2/auth	https://accounts.zoho.sa/oauth/v2/token
.ae	https://accounts.zoho.ae/oauth/v2/auth	https://accounts.zoho.ae/oauth/v2/token

Example request

Every request carries an access token. Authorization accepts either Zoho-oauthtoken or Bearer — both work.

HTTP

GET /vani/api/v1/spaces HTTP/1.1
Host: api.app.vanihq.com
Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN
Content-Type: application/json

Scopes & access levels

Scopes are granular. Every operation on the reference pages declares exactly the scopes it needs — request only those.

Scopes follow the resource nesting. Any operation on a zone can carry a space scope, and operations inside a zone can carry a zone scope — so a token scoped to a space reaches the zones within it. Grant the narrowest scope that covers the operations you call.

editions

Grants access to edition-level operations, including creating, updating, and managing editions, as well as adding or updating edition members.

Method	OAuth scope
GET	Vani.editions.READ
POST	Vani.editions.CREATE

teams

Provides access to team-level operations within an edition, such as creating teams, updating details, managing members (add/remove/change roles), and deleting teams.

Method	OAuth scope
GET	Vani.teams.READ
POST	Vani.teams.CREATE
PUT	Vani.teams.UPDATE
DELETE	Vani.teams.DELETE

spaces

Enables full control over Space-related operations within a team, including creating, updating, and deleting Spaces under a specific edition.

Method	OAuth scope
GET	Vani.spaces.READ
POST	Vani.spaces.CREATE
PUT	Vani.spaces.UPDATE
DELETE	Vani.spaces.DELETE

zones

Allows Zone-level access within a Space, including creating, editing, and deleting Zones for detailed content management.

Method	OAuth scope
GET	Vani.zones.READ
POST	Vani.zones.CREATE
PUT	Vani.zones.UPDATE
DELETE	Vani.zones.DELETE

Authentication errors

Status	Meaning
401	Invalid or missing authentication credentials
403	Valid credentials but insufficient permissions or scopes
429	Rate limit exceeded — retry after the window resets