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. x-vani-apikey

Need an API key? Request one from the 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

Include your access token in the authorization header:

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

Error Responses

Authentication errors will return appropriate 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