# 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.

## 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

1. Register your application and obtain a client ID and secret.
2. Redirect the user to the authorization URL to grant the scopes you request.
3. Exchange the authorization code for an access token and refresh token.
4. Send the access token in the `Authorization` header.
5. Use the refresh token to mint new access tokens.

## Example request

```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

### 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 |