Skip to main content
Connecting Maestro with external services securely.

​
Secret Management System

​
What Are Secrets?

Secrets are secrets (API keys, tokens, passwords) that Maestro needs to interact with external services like:
  • Cloud providers (AWS, Azure, GCP)
  • APIs (GitHub, GitLab, OpenAI)
  • Databases (PostgreSQL, MySQL, MongoDB)
  • Third-party services (Stripe, SendGrid, etc.)

​
Security Model

User-controlled activation:
  • You register secrets once
  • Per-session activation via /secrets command
  • Maestro cannot access without your explicit consent
  • Session-scoped exposure only
Isolation guarantees:
  • Secrets never logged
  • Never shared across sessions
  • Automatic cleanup on session end
  • Encrypted at rest

​
Managing Secrets

​
Secret Manager (UI)

Access: Bottom-left menu → “Manage Secrets” Functions:
  • Register new secrets
  • Edit existing secrets
  • Delete secrets
  • View usage history
  • Configure OAuth integrations

​
Registering Secrets

Manual registration:
  1. Open Secret Manager
  2. Click “Add Secret”
  3. Enter details:
    • Name (e.g., AWS_ACCESS_KEY_ID)
    • Value (the actual secret)
    • Optional: Description, tags
  4. Save (encrypted immediately)
OAuth registration:
  1. Select OAuth provider (GitHub, GitLab, etc.)
  2. Authorize via OAuth flow
  3. Secrets stored automatically
  4. Includes refresh token handling

​
Activating Secrets

Via /secrets command: 
/secrets → Interactive table

Secret             Active
AWS_ACCESS_KEY_ID      ☐
AWS_SECRET_ACCESS_KEY  ☐
GITHUB_TOKEN          ☑
DATABASE_URL          ☐

Toggle switches to activate/deactivate
Confirm changes
Secrets immediately available in sandbox
Via natural language: 
"Activate AWS secrets for this session"

Maestro:
- Uses Manage Secrets tool
- Requests your confirmation
- Activates specified secrets

​
Using Activated Secrets

In sandbox terminals: 
# After activating AWS secrets
echo $AWS_ACCESS_KEY_ID  # Shows value
aws s3 ls                # AWS CLI works

# After activating database URL
psql $DATABASE_URL       # Connects to database
In Maestro’s tool execution:
  • Secrets available to all sandbox commands
  • Automatic injection into environment
  • Tools can use them transparently

​
Deactivating Secrets

When done with sensitive secrets: 
/secrets → Toggle off sensitive secrets

Best practice:
- Activate only when needed
- Deactivate after use
- Minimize exposure window

​
Supported Integrations

​
Cloud Providers

​
AWS

Secrets needed:
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • AWS_REGION (optional, defaults to us-east-1)
What you can do: 
# S3 operations
aws s3 ls s3://my-bucket
aws s3 cp file.txt s3://my-bucket/

# EC2 management
aws ec2 describe-instances

# Lambda deployment
aws lambda update-function-code --function-name my-func --zip-file fileb://func.zip

​
Azure

Secrets needed:
  • AZURE_SUBSCRIPTION_ID
  • AZURE_TENANT_ID
  • AZURE_CLIENT_ID
  • AZURE_CLIENT_SECRET
What you can do: 
az login --service-principal
az storage blob upload
az webapp deploy

​
Google Cloud Platform

Secrets needed:
  • GOOGLE_APPLICATION_CREDENTIALS (path to service account JSON)
What you can do: 
gcloud auth activate-service-account
gcloud storage cp file.txt gs://my-bucket/

​
Version Control

​
GitHub

OAuth integration (recommended):
  • Link account via Secret Manager
  • Automatic token refresh
  • Access private repositories
  • Create/update PRs
Personal Access Token (alternative): 
Register: GITHUB_TOKEN
Activate in session
Full API access based on token scope
Capabilities:
  • Clone private repositories
  • Create and update PRs
  • Add review comments
  • Manage issues
  • Trigger workflows

​
GitLab

OAuth integration:
  • Similar to GitHub
  • Private repository access
  • API operations
Personal Access Token: 
Register: GITLAB_TOKEN
Activate for API access

​
Databases

​
PostgreSQL

Register: DATABASE_URL=postgresql://user:pass@host:5432/dbname

Activate →
psql $DATABASE_URL

​
MySQL

Register: MYSQL_URL=mysql://user:pass@host:3306/dbname

Activate →
mysql -h host -u user -p dbname

​
MongoDB

Register: MONGODB_URI=mongodb://user:pass@host:27017/dbname

Activate →
mongosh $MONGODB_URI

​
API Services

​
OpenAI, Anthropic, etc.

For using AI APIs in your code:

Register: OPENAI_API_KEY
Activate in session
Your code can now use OpenAI API

​
Stripe

Register:
- STRIPE_SECRET_KEY (for API operations)
- STRIPE_PUBLISHABLE_KEY (for client-side)

Use for:
- Payment processing implementation
- Webhook testing
- Subscription management

​
SendGrid, Mailgun

Register email service secrets
Implement email functionality
Test email sending in sandbox

​
OAuth Integration

​
Supported Providers

  • GitHub
  • GitLab
  • Google
  • Microsoft
  • Custom OAuth 2.0 providers

​
OAuth Flow

One-time setup:
  1. Secret Manager → Add OAuth Integration
  2. Select provider
  3. Authorize Maestro
  4. Secrets stored with refresh token
Automatic refresh:
  • Tokens refreshed automatically
  • No manual intervention
  • Always valid when activated
Scope management:
  • OAuth scopes shown during authorization
  • Cannot exceed granted scopes
  • Re-authorize to change scopes

​
OAuth vs Personal Access Tokens

OAuth advantages:
  • Automatic token refresh
  • Granular scope control
  • Revocable via provider
  • Better security
PAT advantages:
  • Simple setup
  • Works in automation
  • No browser required
Recommendation: Use OAuth for interactive work, PATs for automation.

​
Security Best Practices

​
Secret Hygiene

DO:
  • Use descriptive names (AWS_PROD, AWS_DEV)
  • Rotate secrets regularly
  • Use least-privilege scopes
  • Deactivate after use
  • Review active secrets regularly
DON’T:
  • Commit secrets to files
  • Share secrets across teams
  • Use overly permissive tokens
  • Leave secrets activated indefinitely

​
Scope Minimization

Principle: Grant only necessary permissions. Example: 
GitHub token for reading repos: repo:read scope only
Not: full repo access

AWS secrets for S3: s3:ListBucket, s3:GetObject
Not: AdministratorAccess

​
Separation of Environments

Separate secrets per environment: 
AWS_DEV_ACCESS_KEY
AWS_STAGING_ACCESS_KEY
AWS_PROD_ACCESS_KEY

Activate appropriate set per session
Prevents accidental production operations

​
Audit and Monitoring

Track credential usage:
  • Secret Manager shows last used timestamp
  • Review which sessions used secrets
  • Detect unusual usage patterns

​
Troubleshooting

​
Secret Not Working

Check:
  1. Is credential registered in Secret Manager?
  2. Did you activate for this session (/secrets)?
  3. Is credential value correct?
  4. Are scopes sufficient?
  5. Is credential expired?
Verify in sandbox: 
env | grep CREDENTIAL_NAME
# Should show value if activated

​
OAuth Token Expired

Symptoms:
  • API calls fail with 401
  • “Token expired” errors
Solution:
  • Secret Manager → Refresh OAuth token
  • Or re-authorize via OAuth flow
Automatic refresh: Most OAuth tokens refresh automatically; manual intervention rare.

​
Permission Denied

Cause: Insufficient OAuth scopes or IAM permissions Solution:
  • For OAuth: Re-authorize with broader scopes
  • For cloud IAM: Grant additional permissions in cloud console
  • For PATs: Generate new token with required scopes

​
Secret Accidentally Committed

If credential leaked to file: 
Immediate actions:
1. Do NOT create PR or push
2. Remove credential from file
3. Regenerate credential (consider it compromised)
4. Register new credential
5. Update application/service with new credential

Prevention:
- Use .gitignore
- Use environment variables
- Never hardcode secrets

​
Integration Patterns

​
AWS Deployment Example

Goal: Deploy Lambda function

Setup:
1. Register AWS secrets
2. Activate for session

Implementation:
- Maestro writes Lambda function code
- Creates deployment package
- Tests locally in sandbox
- Deploys using AWS CLI
- Verifies deployment

Validation:
- Test deployed Lambda
- Check CloudWatch logs
- Verify IAM permissions

​
Database Migration Example

Goal: Migrate staging database schema

Setup:
1. Register DATABASE_URL (staging)
2. Activate for session

Process:
- Maestro creates migration scripts
- Tests migration on local PostgreSQL (in sandbox)
- Validates migration correctness
- Backs up staging database
- Runs migration on staging
- Verifies schema and data integrity

Safety: Staging only, production requires separate approval

​
Third-Party API Integration

Goal: Implement Stripe payment processing

Setup:
1. Register STRIPE_SECRET_KEY (test mode)
2. Activate for session

Implementation:
- Maestro implements payment flow
- Uses Stripe test API
- Creates webhook handlers
- Tests with Stripe test cards
- Validates webhook signatures

Validation:
- All test scenarios pass
- Webhook delivery confirmed
- Error cases handled

Production: Separate session with production secrets

​
Advanced OAuth Patterns

​
Multiple GitHub Accounts

Register:
- GITHUB_PERSONAL
- GITHUB_WORK

Activate appropriate one per session:
- Personal projects → GITHUB_PERSONAL
- Work projects → GITHUB_WORK

Prevents cross-contamination

​
OAuth Secret Sharing

Within organization:
  • Service accounts for shared resources
  • Team-wide OAuth applications
  • Centralized credential management
Security: Use service principals, not personal accounts for shared access.

​
Next Steps

Secure integration mastered: