Access Tokens and API Keys
Learn how to create and manage access tokens and API keys for programmatic access to your Devpilot workspace.
Access Tokens and API Keys
Devpilot provides two mechanisms for programmatic access to your workspace: access tokens and API keys. Both allow external tools, scripts, CI/CD pipelines, and automation workflows to interact with your workspace without a browser session. This guide explains when to use each, how to create them, and how to manage them securely.
Access Tokens vs. API Keys
Access tokens are workspace-scoped credentials designed for deployment, activity-tracking, and automation scripts. Each token has a set of scopes that control exactly which automation actions it can perform, an optional passphrase for added protection, and an optional expiry date.
Use access tokens when:
- You are wiring up a deployment pipeline or a long-running automation script.
- You want tight, scope-based control over what the credential can do.
- You need a per-script credential with its own passphrase and expiry.
API keys are also workspace-scoped credentials, intended for service-to-service integrations with Devpilot's management APIs. They carry a set of permissions (such as read, write, deploy, manage_servers), an optional description, and an optional expiry.
Use API keys when:
- You are building a service integration that talks to Devpilot's APIs.
- You need a credential that is not tied to a specific automation script.
- You want to manage the credential's permissions and active state over time.
Only workspace Owners and Admins can create, update, or delete access tokens and API keys.
Creating an Access Token
Navigate to Workspace Settings
Open your workspace and go to Settings. Select the Access Tokens tab.
Click "Generate Token"
Select the Generate Token button to open the token creation form.
Name the Token
Provide a descriptive name between 3 and 255 characters (e.g., "CI/CD Pipeline", "Monitoring Script", "Deployment Automation"). The name helps you identify the token's purpose later.
Select Scopes
Choose which actions the token is allowed to perform. At least one scope is required. Available scopes:
| Scope | Description |
|---|---|
all | Grants every access-token capability. |
basic_deployment | Trigger and manage basic deployments. |
advanced_deployment | Perform advanced deployment workflows. |
activity_tracker | Submit activity events to the workspace's activity tracker. |
activity_tracker_analytics | Read activity-tracker analytics. |
error_tracker | Submit and read error-tracker events. |
modify_env | Read and modify environment variables for apps. |
run_scripts | Execute configured automation scripts. |
Select only the scopes your use case requires.
Set a Passphrase (Optional)
You can optionally attach a passphrase of 8 to 255 characters. When set, the passphrase must be supplied alongside the token at use time, adding a second factor in case the token leaks.
Set an Expiry (Optional)
Choose an expiry date in the future, or leave it blank for a non-expiring token.
Non-expiring tokens pose a greater security risk. Prefer short-lived tokens and rotate them regularly.
Copy the Token
After creation, Devpilot displays the token value once. It is prefixed with workspace_token_. Copy it immediately and store it in a secrets manager — the plain token is not shown again, and if you lose it you must delete the token and create a new one.
Never commit access tokens to source control or share them in chat. Store them in a secrets manager or encrypted CI/CD variables.
Creating an API Key
Navigate to Workspace Settings
Open your workspace and go to Settings > API Keys.
Click "Generate API Key"
Select the Generate API Key button to open the creation form.
Name the API Key and Add a Description
Provide a descriptive name between 3 and 255 characters. You can optionally add a description of up to 1000 characters explaining what the key is for.
Set Permissions
Choose one or more permissions for the key. Available permissions:
| Permission | Description |
|---|---|
read | Read workspace resources and metadata. |
write | Create and modify workspace resources. |
delete | Delete workspace resources. |
deploy | Trigger deployments. |
manage_servers | Full management of servers. |
manage_projects | Full management of projects. |
manage_apps | Full management of apps. |
view_logs | Read deployment and application logs. |
manage_backups | Create, restore, and delete backups. |
Pick only what the integration needs.
Set an Expiry (Optional)
Choose an expiry date in the future, or leave it blank for a non-expiring key. You can also mark the key as inactive at creation by clearing the Active toggle.
Copy the API Key
The plain API key is displayed once and is prefixed with dp_. Copy it immediately and store it securely. It cannot be retrieved after you leave this page.
Managing Active Tokens and Keys
The Access Tokens and API Keys tabs in workspace Settings list every credential you have, together with:
- The name you gave it when you created it (and, for API keys, the optional description).
- The scopes or permissions it carries.
- Whether it is currently active.
- When it was created and when it expires (or "Never" if you left expiry blank).
- When it was last used. For access tokens, you'll also see how many times it has been used.
Editing an API Key
API keys can be updated after creation. Open the key and edit the name, description, permissions, expiry, or active state. The key's secret value does not change — only its metadata and authorization are updated. Access tokens, by contrast, are immutable once created; to change a token's scopes or expiry, delete it and create a new one.
Deleting a Token or API Key
To permanently revoke a credential:
- Open the relevant tab (Access Tokens or API Keys) in workspace Settings.
- Find the credential you want to revoke.
- Open the action menu and choose Delete.
- Confirm the action.
The credential stops working immediately. Any scripts, pipelines, or integrations using it will begin to fail with authentication errors.
Deleting a credential does not undo actions already performed with it. Review the activity log if you need to audit past usage.
Rotating Credentials
Devpilot does not auto-rotate credentials. The recommended rotation workflow:
- Create a new token or API key with the same scopes or permissions.
- Update your scripts, pipelines, or integrations to use the new credential.
- Verify the new credential works correctly.
- Delete the old credential.
Security Best Practices
- Use the minimum scope or permission required. A deploy-only token does not need
modify_envorrun_scripts. - Set an expiry. Short-lived credentials shrink the blast radius if a secret leaks.
- Use a passphrase on sensitive access tokens. It adds a second factor that an attacker needs to use the token.
- Store credentials in a secrets manager. Never hardcode them in source, commit them to Git, or paste them in chat.
- Audit regularly. Review the list of active tokens and API keys and delete anything no longer needed or whose purpose is unclear.
- Watch the last-used timestamp and usage count. Credentials that haven't been used in a while often point to abandoned integrations and should be revoked.
- Rotate on team changes. When a teammate who owned scripts leaves, rotate the credentials those scripts used.