Practical workflows for securely connecting Maestro with external services. This guide shows you how to set up and use secrets for cloud providers, APIs, and databases. For security architecture details, see Explanation: Security Model. For complete credential reference, see Reference: Supported Integrations.

Register Secrets

Via Secret Manager UI

Access from bottom-left menu → “Manage Secrets”:
1. Click "Add Secret"
2. Enter secret details:
   - Name (e.g., AWS_ACCESS_KEY_ID)
   - Value (the actual secret key or token)
   - Optional: Description and tags
3. Save (encrypted immediately)

Via OAuth Integration

For supported providers (GitHub, GitLab, Google, Microsoft):
1. Secret Manager → Select OAuth provider
2. Authorize via OAuth flow (redirects to provider)
3. Secrets stored automatically
4. Includes automatic token refresh

Activate Secrets for Session

Use the /secrets Command

/secrets
Opens interactive table showing all registered secrets. Toggle switches to activate/deactivate for the current session, then confirm.

Via Natural Language

"Activate AWS secrets for this session"

"Enable the GitHub token secret"

"Activate database credentials"
Maestro will request your confirmation before activating.

Use Activated Secrets

In Sandbox Operations

Once activated, secrets are available as environment variables:
"Check if AWS credentials are available in the sandbox"

"Show me the value of DATABASE_URL"

"List all active environment variables"
Then use them in operations:
"Use the AWS CLI to list S3 buckets"

"Connect to the PostgreSQL database using DATABASE_URL"

"Make an API request to GitHub using the GITHUB_TOKEN"

For Tool Execution

Maestro’s tools automatically use activated secrets:
"Deploy the Lambda function using AWS credentials"

"Clone my private repository (uses activated GitHub token automatically)"

"Query the production database (uses activated DATABASE_URL)"

Deactivate Secrets

When done with sensitive operations:
/secrets → Toggle off the secrets you no longer need
Or:
"Deactivate AWS production secrets now that deployment is complete"
Best practice: Activate only when needed, deactivate after use to minimize exposure window.

Cloud Provider Setup

AWS Configuration

Register these secrets:
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_REGION (optional, defaults to us-east-1)
Then use:
"Activate AWS secrets"

"List all S3 buckets in my account"

"Deploy the Lambda function to production"

"Check EC2 instances in us-east-1 region"

Azure Configuration

Register:
AZURE_SUBSCRIPTION_ID
AZURE_TENANT_ID
AZURE_CLIENT_ID
AZURE_CLIENT_SECRET
Then use:
"Activate Azure secrets"

"Upload the file to Azure Blob Storage"

"Deploy the web app to Azure"

Google Cloud Configuration

Register:
GOOGLE_APPLICATION_CREDENTIALS (path to service account JSON)
Then use:
"Activate Google Cloud secrets"

"Upload file to the Cloud Storage bucket"

"List all GCP projects I have access to"

Version Control Integration

Link your GitHub account via Secret Manager:
1. Secret Manager → Add OAuth Integration → GitHub
2. Authorize Maestro
3. Automatic token refresh enabled
Now you can:
"Clone my private repository backend-api"

"Create a PR on my work repository"

"Add a review comment on PR #123"

GitHub (Personal Access Token)

Alternatively, register a PAT:
Register: GITHUB_TOKEN=ghp_your_token_here
Activate when needed:
"Activate GitHub token for this session"

GitLab Integration

Similar to GitHub - use OAuth or PAT:
OAuth: Secret Manager → GitLab OAuth
PAT: Register GITLAB_TOKEN=glpat_your_token

Database Connections

PostgreSQL

Register connection URL:
DATABASE_URL=postgresql://user:pass@host:5432/dbname
Use:
"Activate database credentials"

"Connect to the database and show me the users table schema"

"Run the migration script against the database"

"Query the database for users created in the last 24 hours"

MySQL

Similar pattern:
MYSQL_URL=mysql://user:pass@host:3306/dbname

MongoDB

MONGODB_URI=mongodb://user:pass@host:27017/dbname
Then:
"Connect to MongoDB and show collections"

"Query the users collection"

API Services

OpenAI or Anthropic APIs

For using AI APIs in your code:
Register: OPENAI_API_KEY=sk-...
Activate and use:
"Activate OpenAI API key"

"Test the OpenAI API by making a simple completion request"

"Run the script that uses OpenAI embeddings"

Stripe Integration

Register:
STRIPE_SECRET_KEY=sk_test_...  (for API operations)
STRIPE_PUBLISHABLE_KEY=pk_test_...  (for client-side)
Use:
"Activate Stripe secrets"

"Test the payment processing flow with test card"

"Create a test subscription for user testing"

Email Services (SendGrid, Mailgun)

Register email service credentials:
SENDGRID_API_KEY=SG...
Use:
"Activate email service credentials"

"Send a test email to verify the integration works"

"Run the email notification script"

OAuth vs Personal Access Tokens

When to Use OAuth

Advantages:
  • Automatic token refresh (no manual intervention)
  • Granular scope control
  • Revocable via provider UI
  • Better security
Use for: Interactive work, long-term access, GitHub/GitLab integration.

When to Use Personal Access Tokens

Advantages:
  • Simple setup (just copy/paste)
  • Works in automation scenarios
  • No browser required
Use for: CI/CD pipelines, scripts, temporary access.

Security Best Practices

Scope Minimization

Grant only necessary permissions:
GitHub token for reading repos:
- Use repo:read scope only
- Not full repo access

AWS credentials for S3:
- Use s3:ListBucket, s3:GetObject policies only
- Not AdministratorAccess

Environment Separation

Use separate secrets per environment:
AWS_DEV_ACCESS_KEY (development)
AWS_STAGING_ACCESS_KEY (staging)
AWS_PROD_ACCESS_KEY (production)
Activate appropriate set per session to prevent accidental production operations.

Secret Rotation

Rotate secrets regularly:
1. Generate new secret in provider
2. Register new secret in Secret Manager
3. Update applications to use new secret
4. Delete old secret from Secret Manager
5. Revoke old secret in provider

Troubleshoot Issues

Secret Not Working

Check these steps:
"Is the secret registered in Secret Manager?"

"Did I activate it for this session? Show me active secrets."

"Display the secret value to verify it's correct"

"Check if the secret has expired or been revoked"

Permission Denied

For cloud services:
"The AWS operation failed with permission denied. 
Check the IAM policy for my credentials to see what permissions I have."
For OAuth:
"Re-authorize the GitHub OAuth integration with broader scopes"

OAuth Token Expired

If automatic refresh fails:
Secret Manager → Refresh OAuth token

Or re-authorize completely:
Secret Manager → Re-authorize GitHub/GitLab

Secret Accidentally Committed

If you accidentally put a secret in a file:
IMMEDIATE ACTIONS:
1. "Remove the secret from all files immediately"
2. Do NOT create PR or push to GitHub
3. Regenerate the secret (consider it compromised)
4. Register new secret in Secret Manager
5. Update applications with new secret

PREVENTION:
- Always use environment variables
- Never hardcode secrets
- Use .gitignore for config files with secrets

Integration Workflows

AWS Deployment Example

Setup:
"Register AWS secrets in Secret Manager"
"Activate AWS secrets for this session"

Deployment:
"Package the Lambda function code"
"Create deployment package in /tmp"
"Deploy to Lambda using AWS CLI"
"Verify deployment with test invocation"
"Check CloudWatch logs for any errors"

Database Migration Example

Setup:
"Register staging database URL"
"Activate database credentials"

Process:
"Create migration scripts for schema changes"
"Test migration on local PostgreSQL first"
"Backup the staging database"
"Run migration against staging"
"Verify schema and data integrity"
"Show me row counts before and after"

Third-Party API Integration

Setup:
"Register Stripe test key"
"Activate Stripe secrets"

Implementation:
"Implement payment processing flow using Stripe API"
"Create webhook handler for payment events"
"Test with Stripe test card 4242424242424242"
"Verify webhook signature validation works"
"Test error handling with declined card"

Multiple Account Patterns

Multiple GitHub Accounts

Register separately:
GITHUB_PERSONAL (for personal projects)
GITHUB_WORK (for work projects)

Activate appropriate one per session:
"Activate GITHUB_WORK for this session"

This prevents cross-contamination between work and personal repos.

Multiple AWS Accounts

AWS_DEV (development account)
AWS_PROD (production account)

Activate based on task:
Development work: "Activate AWS_DEV credentials"
Production deploy: "Activate AWS_PROD credentials"

Next Steps

Master secret management, then explore: