docs: Self review of doc pages
This commit is contained in:
+42
-137
@@ -1,154 +1,59 @@
|
||||
---
|
||||
id: rest-api
|
||||
title: REST API
|
||||
sidebar_label: REST API
|
||||
title: Automating Vantage
|
||||
sidebar_label: Automating Vantage
|
||||
---
|
||||
|
||||
The control plane's HTTP API, on port `8080`. The web UI is a client of it and
|
||||
has no privileges it does not.
|
||||
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.
|
||||
|
||||
## Authentication
|
||||
The routes mirror the product: `/api/servers`, `/api/keys`, `/api/workflows`,
|
||||
`/api/monitors`, `/api/secrets`, `/api/audit`, and so on.
|
||||
|
||||
Most endpoints take a session: an opaque 32-byte token in the `km_session`
|
||||
cookie, with the body in Redis for 24 hours.
|
||||
## Where it is
|
||||
|
||||
One endpoint takes a bearer token instead the External Secrets Operator read
|
||||
path.
|
||||
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.
|
||||
|
||||
## Unauthenticated
|
||||
## Signing in
|
||||
|
||||
```
|
||||
GET /install /install.ps1 # dynamic agent install scripts
|
||||
GET /update /update.ps1
|
||||
GET /auth/bootstrap-status
|
||||
POST /auth/bootstrap /auth/login /auth/logout
|
||||
GET /auth/me
|
||||
GET /auth/providers # {local_enabled, providers:[{id,name,preset}]} — no issuer, client ID or secret
|
||||
GET /auth/oidc/:providerId/start · /auth/oidc/:providerId/callback
|
||||
GET /api/secrets/:group/values # bearer token (ESO)
|
||||
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
|
||||
```
|
||||
|
||||
`/install` and `/install.ps1` take `server_id` and `token` as query parameters
|
||||
and return a shell script with the newest agent version substituted in.
|
||||
Sessions last 24 hours. Your role applies exactly as it does in the UI: a
|
||||
`member` calling an owner-only route is refused.
|
||||
|
||||
`POST /auth/bootstrap` works only while the database has no users.
|
||||
## The one exception
|
||||
|
||||
## Session-authenticated, under `/api`
|
||||
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).
|
||||
|
||||
### Servers
|
||||
## Things worth knowing
|
||||
|
||||
```
|
||||
GET,POST /servers
|
||||
GET,POST /servers/new
|
||||
GET,DELETE /servers/:id
|
||||
POST /servers/:id/generate-key
|
||||
POST /servers/:id/update-agent
|
||||
POST /servers/:id/apply-updates
|
||||
```
|
||||
- **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).
|
||||
|
||||
### Keys
|
||||
## Vantage HQ
|
||||
|
||||
```
|
||||
GET,POST /keys
|
||||
GET,DELETE /keys/:id
|
||||
GET /keys/:id/private-key
|
||||
POST /keys/:id/assign
|
||||
DELETE /keys/:id/assign/:serverId
|
||||
```
|
||||
|
||||
### Workflows and steps
|
||||
|
||||
```
|
||||
GET,POST /steps
|
||||
PUT,DELETE /steps/:id
|
||||
GET /steps/:id/export
|
||||
POST /steps/import · /steps/seed-defaults · /steps/parse
|
||||
GET /steps/usage
|
||||
GET,POST /workflows
|
||||
GET,PUT,DELETE /workflows/:id
|
||||
POST /workflows/:id/run
|
||||
GET /workflows/:id/runs
|
||||
GET /runs/:runId
|
||||
POST /runs/:runId/cancel
|
||||
GET /runs/:runId/servers/:serverId/logs
|
||||
GET /runs/:runId/servers/:serverId/logs/stream
|
||||
```
|
||||
|
||||
`PUT` and `DELETE` on a step whose source is `default` answer `409`. See
|
||||
[Workflows](../vantage/workflows.md#default-steps).
|
||||
|
||||
### Monitors and channels
|
||||
|
||||
```
|
||||
GET,POST /monitors
|
||||
GET,PUT,DELETE /monitors/:id
|
||||
GET /monitors/:id/incidents · /monitors/:id/uptime
|
||||
GET,POST /channels
|
||||
PUT,DELETE /channels/:id
|
||||
POST /channels/:id/test
|
||||
```
|
||||
|
||||
### Secrets
|
||||
|
||||
```
|
||||
GET,POST /secrets
|
||||
GET,PUT,DELETE /secrets/:group
|
||||
POST /secrets/:group/reveal
|
||||
DELETE /secrets/:group/:key
|
||||
```
|
||||
|
||||
### Console
|
||||
|
||||
```
|
||||
POST /console/connect
|
||||
GET /console/tunnel # websocket
|
||||
```
|
||||
|
||||
### Other
|
||||
|
||||
```
|
||||
GET /audit
|
||||
GET /agent/latest-version
|
||||
GET,PUT /settings (owner|admin)
|
||||
POST /settings/secrets-token (owner|admin)
|
||||
GET /license
|
||||
POST /license (self-hosted only)
|
||||
GET,POST /org/users
|
||||
PUT /org/users/:id/role
|
||||
DELETE /org/users/:id
|
||||
GET,POST /auth/providers (owner|admin)
|
||||
PUT,DELETE /auth/providers/:id (owner|admin)
|
||||
POST /auth/providers/:id/test · /auth/providers/:id/ack-notice (owner|admin)
|
||||
GET /auth/presets (owner|admin)
|
||||
```
|
||||
|
||||
## Notable refusals
|
||||
|
||||
| Endpoint | Condition | Status |
|
||||
| -------------------------------------------------- | ------------------------------ | ------------------- |
|
||||
| `POST /license` | deployment is `cloud` | `409 cloud_managed` |
|
||||
| `PUT,DELETE /steps/:id` | the step's source is `default` | `409` |
|
||||
| `PUT /org/users/:id/role`, `DELETE /org/users/:id` | the user's auth source is `hq` | `409` |
|
||||
|
||||
`POST /license` is exempt from the licence check, so pasting a valid licence
|
||||
works while the current one is expired that is the way out of degraded mode.
|
||||
|
||||
## Multi-tenancy
|
||||
|
||||
Every request is scoped to the instance resolved from the session. On a
|
||||
multi-tenant deployment, a request arriving at `<slug>.vantage.<tld>` also has
|
||||
its host checked against the session's instance, and a mismatch is rejected.
|
||||
|
||||
## Errors
|
||||
|
||||
Errors are JSON with an `error` field. Customer-facing endpoints in the HQ API
|
||||
answer `404` rather than `403` for another account's resource, because a `403`
|
||||
confirms the resource exists; the control plane's own API is single-tenant per
|
||||
session and does not need that distinction.
|
||||
|
||||
## Admin API
|
||||
|
||||
Vantage HQ is a separate hosted service with its own API and its own session.
|
||||
Its behaviour is described in the [Vantage HQ](../hq/accounts-and-signup.md)
|
||||
section rather than here; the two services share no session and no
|
||||
authentication.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user