Apps, installations and clients

Give a script or service its own identity and OAuth credentials for the Vigilfield API.

Use an app when a script, pipeline or service needs to call the Vigilfield API without a person signed in. Three objects work together:

App. A non-human identity in your organization. It declares the permissions it needs, but it holds no access on its own. An app survives personnel changes: it has an owner admin who is accountable for it, and you can reassign that owner.
Installation. A team installs an app. The installation grants the app specific permissions on that team's resources. Each installation belongs to exactly one team.
Client. An OAuth client-credentials credential (a client id and a client secret) issued against one installation. Your workload exchanges it for a short-lived access token. See API authentication.

A client acts as the app, on the team that installed it, and never with more than that installation granted.

Create an app

Only administrators can create apps.

In the sidebar, open Apps.
Click New App.
Enter a Name (up to 80 characters), for example etl-pipeline-prod.
Click Create.

The app starts as active. Its detail page shows its Id, a Synthetic email and the Owner admin. To hand the app to another administrator, for example before someone leaves, click Reassign.

The Apps page has three tabs:

Installed — apps your teams have installed. This is the default tab.
Authored — apps owned by a team you belong to.
Catalog — published, active apps.

Seeing apps needs the apps:read capability. Administrators have it, and it can also be granted to a team.

The New App form sets only a name. An app created this way declares no permissions, so an installation of it can grant nothing. To declare the permissions an app needs, pass required_permissions when you create it through the API (Create an app), or add them later with Update an app.

Declaring permissions

required_permissions is a list of resource:action tokens. Declaring a permission grants nothing. It only lists what an installer may approve.

An app can be granted these permissions:

Resource	Actions
`tables`	`read`, `write`, `query`, `export`
`sources`	`read`, `write`
`investigations`	`read`, `write`
`rules`	`read`, `write`
`folders`	`read`, `write`
`alert_destinations`	`read`, `write`

An app can never hold an administrator or owner role.

Install an app

The app has no install button yet, and this request is not in the API reference yet. An installation is made by a signed-in user (not by a client) with POST /apps/<app-id>/installations and this body:

{ "permissions": [{ "scope": "tables:read", "target": "*" }] }

The app is installed into the team you are acting as (the x-vf-team-id header), which must be one of your own teams. The body has no team field.
Each scope must be in the app's declared permissions. target is * for every resource of that kind, or one resource id.
You must hold each permission you approve on the resource you name. You cannot give an app more than you have.
The response is 201 with the installation id (inst-…) and one grant per approved permission. A second install of the same app by the same team returns 409.

The Installations card on the app's page lists installations held by teams you belong to. The app may also be installed by a team you are not on.

Create a client

Only administrators can create clients.

Open Apps and select the app.
In Create client, enter a Name, for example ci-runner.
Pick the Installation. Each option reads as app name — team name.
Under Scopes, choose a Resource and an Action, then click Add. Repeat for each scope. At least one scope is required.
Click Create client.

The scopes you pick must fall within what the installation granted. Anything beyond it is refused.

The client secret is shown once, in the dialog that opens after you create the client. Vigilfield stores only a hash of it. Copy it before you click I've copied the secret. If you lose it, you cannot recover it: create a new client and delete the old one.

The secret starts with vfcs_. The client id has the form <installation-id>.client-…, so it names its installation.

You can also create clients with Create a client. The response carries client_secret once. Update a client can rename it or change its scopes; the new scopes are checked against the installation again.

Limits

Two clients per installation. The second slot is for rotation, not for a second workload. A third create returns 409. If another workload needs access, give it its own app, so each one can be granted and revoked on its own.
A client's access follows its installation. A token carries the client's scopes narrowed to the installation's current grants. If a grant is removed later, new tokens lose it.

Rotate a client secret

There is no rotate action. Replace the credential instead:

Create a second client against the same installation, with the same scopes. Copy its secret.
Deploy the new client id and secret to your workload.
Confirm the workload uses the new credential.
Delete the old client.

If the installation already holds two clients, you must delete one first, so the swap is not seamless.

Delete a client, uninstall, delete an app

Delete a client (trash icon in the Clients list). The client can no longer get new tokens. Tokens it already obtained stay valid until they expire, up to 15 minutes. To stop one sooner, revoke it (see API authentication).
Uninstall (on the Installations card). This removes every permission the installation granted and permanently deletes every client issued against it. Tokens already issued from those clients stop working. Only the team that installed the app can uninstall it — switch to that team first. Being an administrator does not substitute.
Delete an app (trash icon on the Apps page). The app is marked inactive and its clients stop authenticating. Its audit history stays. This cannot be undone.