EnvVar Manager User Manual#

Overview#

EnvVar Manager is a web application for storing, organizing, and retrieving environment variables across multiple projects and environments. It supports both browser-based management and API-based access for approved client applications.

From a user perspective, the application lets you:

• Sign in with your user account
• Create and manage projects
• Store environment variables per environment
• Mark sensitive values as secrets
• Export project variables as JSON
• Manage API client applications and their permissions
• Access variables programmatically through a JWT-protected API

Who This Manual Is For#

This manual is intended for end-users of the application, including:

• Viewers: can view projects and environment variables
• Managers: can create and update projects and variables
• Admins: can do everything, including deleting items and managing API applications

Access and Navigation#

Signing In#

When you open the application, unauthenticated users are redirected to the login page.

Login fields#

• Username
• Password
• Remember me

After a successful login, you are typically taken to the Projects page.

Default seeded credentials#

In a default setup, the application may include these initial credentials:

Important: Change default credentials in any real environment.

Main Navigation#

After signing in, the left navigation menu may show:

• Home
• Projects
• API Docs
• Applications (Admins only)

The top bar also shows:

• Your signed-in username
• A Logout button

Roles and Permissions#

User Roles#

Feature Availability by Role#

Home Page#

The Home page provides a high-level introduction to the application and highlights these core capabilities:

• Encrypted Storage: secret values are encrypted at rest
• Multi-Environment: separate values for Development, Staging, and Production
• API Access: JWT-based access for external clients

There is also a prominent View Projects button to jump into project management.

Suggested screenshot#

• A full-page capture of the Home page showing the three feature cards and the View Projects button.

Working with Projects#

Projects List#

Open Projects from the navigation menu to see all available projects.

For each project, the page shows:

• Project name
• Description
• Number of environment variables
• Creation date
• Available actions

Available actions#

• View: opens the project details
• Delete: available to Admins only

If no projects exist#

You will see a message indicating that no projects were found.

Create a New Project#

Available to Managers and Admins.

Steps#

1. Open Projects
2. Click Add Project
3. Enter:
   • Project Name
   • Description
4. Click Create Project

Result#

The project is added to the list and becomes available for storing environment variables.

Suggested screenshot#

• The Projects page with the Add Project modal open.

Delete a Project#

Available to Admins only.

Steps#

1. Open Projects
2. Find the target project
3. Click Delete
4. Confirm the prompt

Important#

Deleting a project also deletes all of its environment variables.

Working with Environment Variables#

Open a Project#

To manage variables:

1. Open Projects
2. Click a project name or View

This opens the Project Detail page.

Project Detail Page#

The project page includes:

• Project title and description
• Environment selector:
  • Development
  • Staging
  • Production
• Table of environment variables for the selected environment
• Actions to add, edit, delete, show/hide, copy, or export values

Switch Between Environments#

Use the environment buttons near the top of the project page to switch between:

• Development
• Staging
• Production

Only variables for the selected environment are shown.

Add an Environment Variable#

Available to Managers and Admins.

Steps#

1. Open a project
2. Click Add Variable
3. Fill in:
   • Key: variable name, such as API_KEY
   • Value: the variable value
   • Environment: Development, Staging, or Production
   • Is Secret: check if the value is sensitive
   • Description: optional explanation
4. Click Save

Example#

Key: API_KEY
Value: my-secret-key
Environment: Production
Is Secret: checked
Description: API key for payment service

What “Is Secret” Means#

If Is Secret is enabled:

• The value is stored encrypted at rest
• The UI treats it as a secret value
• It is shown masked by default on the project page

View and Reveal Secret Values#

For secret variables, the value field is masked.

Steps#

1. Open the project
2. Find the secret variable
3. Click Show to reveal the value
4. Click Hide to mask it again

Copy a Variable Value#

Both normal and secret values can be copied.

Steps#

1. Open the project
2. Find the variable
3. Click Copy

The value is copied to your clipboard.

Edit an Environment Variable#

Available to Managers and Admins.

Steps#

1. Open the project
2. Find the variable
3. Click Edit
4. Update the fields
5. Click Save

You can change:

• Key
• Value
• Environment
• Description
• Secret status

Delete an Environment Variable#

Available to Admins only.

Steps#

1. Open the project
2. Find the variable
3. Click Delete
4. Confirm the prompt

Export Variables as JSON#

The project page includes an Export as JSON button.

Steps#

1. Open a project
2. Select the desired environment
3. Click Export as JSON

Result#

The application generates a JSON object of key/value pairs for the selected environment and copies it to your clipboard.

Example exported JSON#

{
  "API_KEY": "your-api-key",
  "DATABASE_URL": "your-database-url"
}

Note#

The current UI copies the JSON to the clipboard rather than downloading a file.

Suggested screenshot#

• Project Detail page showing environment selector, variable table, and Export as JSON.

Managing API Applications#

Available to Admins only.

API applications represent approved external clients that can authenticate and retrieve or modify environment variables through the API.

Applications List#

Open Applications to view all API clients.

For each application, the page shows:

• Name
• Client ID
• Status
• Created date
• Actions

Available actions#

• Permissions
• Rotate
• Disable or Enable
• Delete

Create an API Application#

Steps#

1. Open Applications
2. Click Create Application
3. Enter an application name
4. Click Create

Result#

A modal appears showing:

• Application name
• Client ID
• Client Secret

Important#

The client secret is shown only once. Copy it immediately.

Suggested screenshot#

• Create New Application modal
• Follow-up modal displaying client ID and client secret

Copy Client ID or Secret#

In the secret display modal:

• Click Copy next to Client ID
• Click Copy next to Client Secret

Rotate an Application Secret#

Rotating the secret invalidates the previous one.

Steps#

1. Open Applications
2. Find the application
3. Click Rotate
4. Confirm the action
5. Copy the new secret from the modal

Important#

The old secret stops working immediately.

Enable or Disable an Application#

Steps#

1. Open Applications
2. Find the application
3. Click Disable or Enable

When disabled#

The client application can no longer authenticate successfully.

Delete an Application#

Steps#

1. Open Applications
2. Find the application
3. Click Delete
4. Confirm the action

Important#

Deleting an application also removes its permissions.

Managing Application Permissions#

Available to Admins only.

Permissions define which application can access which project and environment, and what it may do.

Open Application Permissions#

1. Open Applications
2. Click Permissions for an application

The Application Detail page displays:

• Application name
• Status
• Client ID
• A permissions table

Permission Types#

Each permission record is tied to:

• A project
• An environment
• A set of allowed actions

Supported actions:

• Read
• Write
• Delete

Add a Permission#

Steps#

1. Open an application’s detail page
2. Click Add Permission
3. Choose:
   • Project
   • Environment
4. Set the permission checkboxes:
   • Read
   • Write
   • Delete
5. Click Save

Example#

For a deployment tool that should read production secrets but not modify them:

• Read: enabled
• Write: disabled
• Delete: disabled

Edit a Permission#

Steps#

1. Open an application’s detail page
2. Find the permission
3. Click Edit
4. Update the action checkboxes
5. Click Save

When editing, the project and environment stay fixed.

Delete a Permission#

Steps#

1. Open an application’s detail page
2. Find the permission
3. Click Delete
4. Confirm the prompt

Suggested screenshot#

• Application detail page showing permission rows and the Add Permission modal.

Using the API#

The application includes a built-in API Docs page available to authenticated users with Viewer, Manager, or Admin roles.

API Login#

To use the API, you need:

• A valid application username and password
• A valid API client application
• The client ID and client secret for that application

Login endpoint#

POST /api/auth/login

Request body#

{
  "username": "admin",
  "password": "your_password",
  "clientId": "envvarmanager-cli",
  "clientSecret": "your_client_secret"
}

Response#

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "clientId": "envvarmanager-cli",
  "applicationName": "Default Approved Client"
}

Use the returned JWT token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

Common API Tasks#

Get All Projects#

GET /api/envvars/projects

Get One Project#

GET /api/envvars/projects/{id}

Create a Project#

POST /api/envvars/projects

{
  "name": "My Project",
  "description": "Project description"
}

Get Environment Variables for a Project#

GET /api/envvars/projects/{projectId}/envvars?environment=Development

Create an Environment Variable#

POST /api/envvars/envvars

{
  "projectId": 1,
  "key": "API_KEY",
  "value": "your-secret-value",
  "environment": "Development",
  "description": "API key for external service",
  "isSecret": true
}

Export Environment Variables#

GET /api/envvars/projects/{projectId}/export?environment=Development

cURL Examples#

1. Login#

curl -X POST https://localhost:5001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"ChangeMe123!","clientId":"envvarmanager-cli","clientSecret":"ChangeMeClientSecret123!"}'

2. Get Projects#

curl -X GET https://localhost:5001/api/envvars/projects \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

3. Create Project#

curl -X POST https://localhost:5001/api/envvars/projects \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Project","description":"My project description"}'

4. Create Environment Variable#

curl -X POST https://localhost:5001/api/envvars/envvars \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":1,"key":"API_KEY","value":"secret123","environment":"Development","isSecret":true}'

5. Export Variables#

curl -X GET "https://localhost:5001/api/envvars/projects/1/export?environment=Development" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

User Configuration Options#

From the user-facing behavior in this project, the main configurable items are:

Session Options#

• Remember me during login

Project Data Options#

• Project name
• Project description

Environment Variable Options#

• Key
• Value
• Environment
• Secret/non-secret flag
• Description

API Application Options#

• Application name
• Active/inactive status
• Rotated client secret
• Per-project and per-environment permissions

System-Level Seeded Defaults#

Some deployments may include default seeded values:

These are deployment defaults, not values changed through the UI.

Troubleshooting#

I am redirected to the login page#

Possible causes:

• You are not signed in
• Your session expired

What to do:

1. Sign in again
2. If needed, use the original page URL after login

“You are not authorized to access this resource.”#

Possible causes:

• Your account role does not allow the page or action
• You are signed in as a Viewer trying to manage data
• You are signed in as a Manager trying to delete data or manage applications

What to do:

1. Verify your role with an administrator
2. Sign in with an account that has the required permissions

Secret value is not visible#

This is expected behavior for secret variables.

What to do:

1. Click Show next to the secret field
2. Use Copy if you only need the value temporarily

Export as JSON did not download a file#

This is expected in the current UI.

What happens instead:

• The JSON is copied to your clipboard

What to do:

1. Click Export as JSON
2. Paste the content where needed, such as a file or terminal

I cannot log in to the API#

Possible causes:

• Wrong username or password
• Wrong client ID or client secret
• The API application is disabled
• The application lacks the required project/environment permission

What to check:

1. Verify user credentials
2. Verify client credentials
3. Confirm the API application is active
4. Confirm permissions exist for the requested project and environment

API returns unauthorized or forbidden#

401 Unauthorized#

Usually means:

• Missing or invalid JWT token
• Invalid application credentials during login

403 Forbidden#

Usually means:

• The application is authenticated but does not have permission for the requested project/environment/action

What to do:

1. Re-authenticate and get a fresh token
2. Confirm permission settings in Applications
3. Confirm the correct environment is being requested

An action fails after rotating a client secret#

Possible cause:

• The old secret is no longer valid

What to do:

1. Update the external client configuration with the new secret
2. Log in again to obtain a new JWT token

The page says “Rejoining the server...”#

This application uses interactive server-side components.

What it means:

• The browser temporarily lost connection to the server

What to do:

1. Wait a few seconds for reconnection
2. If reconnection fails, click Retry
3. If needed, reload the page

Error page appears#

If the application shows a general error page:

1. Reload the page
2. Try the action again
3. Contact your administrator if the problem continues

If available, include the request ID shown on the error page.

Recommended Operating Practices#

• Use different variables for Development, Staging, and Production
• Mark sensitive values as secrets
• Limit delete permissions to only the applications that truly need them
• Rotate API client secrets periodically
• Remove unused applications and permissions
• Replace default seeded credentials immediately

Quick Task Guides#

Add a project and store a secret#

1. Sign in as Manager or Admin
2. Open Projects
3. Click Add Project
4. Create the project
5. Open the project
6. Click Add Variable
7. Enter the key and value
8. Check Is Secret
9. Save

Copy production variables as JSON#

1. Open Projects
2. Open the target project
3. Click Production
4. Click Export as JSON
5. Paste the copied JSON where needed

Create an API client for read-only production access#

1. Sign in as Admin
2. Open Applications
3. Click Create Application
4. Copy the client ID and secret
5. Open the application’s Permissions
6. Click Add Permission
7. Select the project
8. Select Production
9. Enable Read
10. Disable Write and Delete
11. Save

Diagram Description#

High-level user flow#

User logs in
   -> opens Projects
   -> selects a project
   -> chooses an environment
   -> views/adds/edits/copies/exports variables

Admin logs in
   -> opens Applications
   -> creates API client
   -> copies client credentials
   -> assigns project/environment permissions
   -> external app logs in through API
   -> external app reads or manages variables based on granted permissions

Conclusion#

EnvVar Manager provides a straightforward way to manage environment variables securely across projects and environments, while also supporting controlled API access for external tools and services. For most daily use, end-users will spend their time in the Projects area, while administrators will also manage Applications and API permissions.