---
id: settings
title: Settings
sidebar_label: Settings
---

One page, three groups: **Access**, **Monitoring** and **Integrations**. Plus
the licence, which has its own page.

Settings require the `owner` or `admin` role.

:::info Where instance settings went
Members and single sign-on used to live at `/settings/instance`. They are now
the Access group at the top of this page splitting "who can sign in" from "how
this instance behaves" produced two half-pages and a nav entry nobody could
distinguish from Settings. The old path still redirects.
:::

:::danger Upgrading breaks existing single sign-on until you re-register the callback URL
Callback URLs are now per provider instead of one shared URL for the whole
instance. If you already had single sign-on configured, it was carried
forward automatically, but its callback URL changed and **sign-in through it
will fail until you copy the new callback URL from its settings card and
register it with your identity provider**. The migrated provider's card shows
a dismissable warning as a reminder. Password sign-in is not affected by this
change, so an administrator can always sign in locally to make the update.
:::

## Access

### Members

Add, remove and re-role the people who can sign in.

| Role     | Can                                                  |
| -------- | ---------------------------------------------------- |
| `owner`  | Everything                                           |
| `admin`  | Everything except owner-only settings                |
| `member` | Servers, keys, workflows, monitors, secrets, console |

Local members authenticate with email and a bcrypt-hashed password.

#### Members managed by Vantage HQ

On a cloud instance, people granted access from the HQ portal appear here as
read-only rows with a link to the portal.

:::warning HQ-managed users cannot be edited locally
Changing the role of, or deleting, an `hq`-sourced user is refused with `409`.
HQ owns their role, their password and whether they exist at all a local
change would be overwritten by the next sync and would leave two writers for one
password hash. Manage them from [People and roles](../hq/people-and-roles.md).
:::

### Single sign-on

Add as many identity providers as you need: one instance can have several at
once, each with its own name, its own button on the login page and its own
callback URL.

Pick a provider from the list of presets:

| Preset                 | You provide                                |
| ---------------------- | ------------------------------------------- |
| Microsoft Entra ID     | Directory (tenant) ID                       |
| Google Workspace       | nothing further, the issuer is fixed        |
| Okta                   | Your Okta org domain                        |
| GitHub                 | Client ID and client secret only            |
| Other (OpenID Connect) | The issuer URL of your identity provider    |

Every provider also needs a **Client ID** and **Client secret**; the secret is
stored AES-256-GCM encrypted and never shown again after you save it.

:::info GitHub requires a verified primary email
Vantage signs a person in by their email address. GitHub is asked for the
account's addresses and only accepts one that is **both** the account's
primary address **and** marked verified: an address GitHub has not confirmed
is not proof anyone controls it.
:::

#### Callback URL

Each provider gets its own callback URL, shown on its settings card with a
copy button. This is the address you register with the identity provider when
you set up the application on their side: each provider is registered
separately, even if you have several with the same identity provider.

#### Turning off password sign-in

You can disable local (email and password) sign-in once at least one provider
is enabled. Vantage refuses to save a change that would leave nobody able to
sign in, whether that change comes from the local login toggle or from
disabling the last enabled provider. Keep at least one option open until every
person who needs access can reach the new one.

## Monitoring

- **Alert defaults** for monitors.
- **Notification channels** their own page. See
  [Notification channels](./notification-channels.md).

## Integrations

### Workflow log retention

How long run logs are kept.

| Value    | Meaning        |
| -------- | -------------- |
| unset    | 30 days        |
| a number | that many days |
| `0`      | forever        |

### ESO read token

The bearer token External Secrets Operator uses to read secret groups. Shown
once, stored as a SHA-256 hash, rotatable. See
[Secrets](./secrets.md#kubernetes-external-secrets-operator).

## Licence

`/settings/license` shows the deployment, tier, server allowance, enabled
features and expiry.

On **self-hosted**, paste a licence here. This works even while the current
licence is expired that is the way out of degraded mode.

On **cloud**, there is no paste form. The endpoint answers `409 cloud_managed`,
because a cloud licence is written by HQ directly. The page links to the portal
instead.

See [Licensing and entitlements](../hq/licensing-and-entitlements.md).

## Sessions

Sessions are an opaque token in the `km_session` cookie, held in Redis with a
24-hour TTL. There is no per-session management UI; restarting Redis signs
everyone out and affects nothing else.

## Host and organisation guard

On a multi-tenant deployment, a request to `<slug>.vantage.<tld>` resolves the
organisation from the slug and rejects a session belonging to a different one.
The label it looks for comes from `APP_ROOT_LABEL`.

:::warning A wrong `APP_ROOT_LABEL` disables the guard
It does not fail loudly it simply stops matching, and the host check stops
protecting anything. If you serve the UI on a custom domain, set it to match.
:::