---
id: rest-api
title: Automating Vantage
sidebar_label: Automating Vantage
---

Everything the web UI does, it does through Vantage's own API, so anything you
can do on screen you can also do from a script.

The routes mirror the product: `/api/servers`, `/api/keys`, `/api/workflows`,
`/api/monitors`, `/api/secrets`, `/api/audit`, and so on.

## Where it is

On a self-hosted install the API is served on port `8080`, behind the same
reverse proxy as the web UI, under `/api` and `/auth`. On a cloud instance it is
your instance hostname.

## Signing in

Most calls use a session, exactly as the browser does:

```bash
curl -c cookies.txt -X POST https://vantage.example.com/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"..."}'

curl -b cookies.txt https://vantage.example.com/api/servers
```

Sessions last 24 hours. Your role applies exactly as it does in the UI: a
`member` calling an owner-only route is refused.

## The one exception

Kubernetes reads secret groups with a token instead of a session, so that it
does not need an account. See
[Secrets](../vantage/secrets.md#kubernetes-external-secrets-operator).

## Things worth knowing

- **Reads always work. Changes need a valid licence.** Without one, the instance
  is read-only and any call that changes something is refused. Deleting things,
  applying OS updates and installing a licence are always allowed, so you can
  always get back under your allowance or out of read-only mode.
- **Some features are licensed.** The browser console, single sign-on and
  vulnerability scanning are refused if your licence does not include them.
- **Some things cannot be changed here.** A cloud instance refuses a pasted
  licence, and people managed by Vantage HQ cannot be re-roled or deleted inside
  the instance.
- **Errors are JSON**, with an `error` field naming the reason.
- **Everything that changes something is audited**, whether it came from the UI
  or from a script. See [Audit log](../vantage/audit-log.md).

## Vantage HQ

The portal is a separate service with its own sign-in, described in the
[Vantage HQ](../hq/accounts-and-signup.md) section. A Vantage session does not
work there, and an HQ session does not work in your instance.