Help Doc Access Vani

Authentication

Access to these APIs is secured using OAuth 2.0 and API Key methods.

OAuth 2.0 for Authentication

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

API Key for Authorization

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

Need an API key? Request one from Vani team at support@vanihq.com

OAuth 2.0 Flow

Vani uses the standard OAuth 2.0 authorization code flow. Follow these steps to authenticate:

Authentication Steps

  1. Register your application — Get your client ID and secret
  2. Redirect user to authorization URL — User grants permissions
  3. Exchange authorization code — Get access and refresh tokens
  4. Make API requests — Include access token in authorization header
  5. Refresh tokens — Use refresh token to get new access tokens

Example Request

Use either an OAuth access token or an API key. Do not send both unless instructed by Vani support.

HTTP
GET /vani/api/v1/spaces HTTP/1.1 Host: api.app.vanihq.com Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN Content-Type: application/json # API key alternative GET /vani/api/v1/spaces HTTP/1.1 Host: api.app.vanihq.com x-vani-apikey: YOUR_API_KEY Content-Type: application/json

Error Responses

Authentication failures return one of the following HTTP status codes:

  • 401 Unauthorized — Invalid or missing authentication credentials
  • 403 Forbidden — Valid credentials but insufficient permissions
  • 429 Too Many Requests — Rate limit exceeded

OAuth Scopes & Access Levels

  • 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