Skip to main content
Version: Next

Applications & Clients

Secrets Manager uses a two-level hierarchy to control which machines and services can access which secrets. Applications group related clients together; Clients are the individual credential sets that authenticate against the API.

Applications​

An application represents a logical system boundary. Common examples:

  • Production API — all services that make up the live product.
  • Staging Environment — mirrors production but uses separate credentials.
  • CI/CD Pipeline — build servers and deployment runners.
  • Developer Workstations — local machines that need access to shared dev secrets.

Creating an Application​

  1. Open the web vault and navigate to Secrets Manager > Applications.
  2. Click New Application.
  3. Enter a name and optional description.
  4. Click Create.

The application is now ready to receive clients.

Clients​

A client is an individual credential set that belongs to an application. Each client gets its own client_id (a UUID) and a one-time access token used for the bootstrap handshake. After bootstrap, the client authenticates with an ECDSA P-256 signed JWT.

Typical clients within a "Production API" application:

Client NamePurpose
Web Server 1Primary application server
Web Server 2Secondary application server
CI DeployGitHub Actions deployment step
Cron WorkerBackground job runner

Creating a Client​

  1. Open the application you created above.
  2. Click New Client.
  3. Enter a descriptive name (e.g., "CI Server — GitHub Actions").
  4. Click Create.

The web vault displays a one-time access token:

vft_eyJhbGciOiJFUzI1NiIs...

Copy this token immediately. It is shown only once and cannot be retrieved later. If you lose it, delete the client and create a new one.

Bootstrapping a Client​

Pass the one-time token to the sy CLI or an SDK to complete the bootstrap handshake:

sy init --token vft_eyJhbGciOiJFUzI1NiIs... --server https://vault.example.com

During bootstrap:

  1. The client sends the token to POST /api/sm/v1/bootstrap.
  2. The server validates the token, returns encrypted key material, and permanently invalidates the token.
  3. The client stores the key material locally and generates an ECDSA P-256 key pair for future authentication.

After this step, the client can authenticate independently using signed JWTs.

Folder Access​

Clients do not access individual secrets directly. Instead, you grant a client access to one or more shared folders. Every secret inside a granted folder is readable by that client — including secrets added after the grant is created.

Granting Folder Access​

  1. Open the client detail page.
  2. Click Add Folder Access.
  3. Select one or more shared folders from the list.
  4. Click Grant Access.

Access is read-only. Clients cannot create, update, or delete secrets through the Secrets Manager API.

Revoking Folder Access​

To revoke access, open the client detail page, find the folder grant, and click Remove. The change takes effect immediately; the client's next API call for secrets in that folder will return a 403.

Lifecycle Management​

Regenerating a Client Token​

If a client needs to be re-bootstrapped (for example, after a machine is reimaged), you can generate a new one-time token from the client detail page. The previous key material becomes invalid and the client must call sy init again.

Deleting a Client​

Deleting a client immediately revokes all access. Any in-flight requests authenticated with that client's JWT will fail. Active sy agent processes on the target machine will lose connectivity.

Deleting an Application​

Deleting an application deletes all of its clients. This is a destructive operation and cannot be undone.

Best Practices​

  • One client per machine or pipeline. If a CI server is compromised you can revoke that single client without affecting other machines.
  • Use descriptive names. "web-prod-us-east-1a" is better than "server1."
  • Audit regularly. The web vault shows the last-used timestamp for each client. Remove clients that have not authenticated recently.
  • Rotate bootstrap tokens quickly. Generate the token, run sy init, and confirm the bootstrap succeeded within minutes. Do not store tokens in ticketing systems or chat logs.