Integrations secrets

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:

Open Secret Manager
Click “Add Secret”
Enter details:
- Name (e.g., AWS_ACCESS_KEY_ID)
- Value (the actual secret)
- Optional: Description, tags
Save (encrypted immediately)

OAuth registration:

Select OAuth provider (GitHub, GitLab, etc.)
Authorize via OAuth flow
Secrets stored automatically
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:

Secret Manager → Add OAuth Integration
Select provider
Authorize Maestro
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:

Is credential registered in Secret Manager?
Did you activate for this session (/secrets)?
Is credential value correct?
Are scopes sufficient?
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

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:

Troubleshooting: Common issues and solutions
FAQ: Frequently asked questions
Best Practices: Production-ready patterns
Billing: Understanding costs and plans

​Secret Management System

​What Are Secrets?

​Security Model

​Managing Secrets

​Secret Manager (UI)

​Registering Secrets

​Activating Secrets

​Using Activated Secrets

​Deactivating Secrets

​Supported Integrations

​Cloud Providers

​AWS

​Azure

​Google Cloud Platform

​Version Control

​GitHub

​GitLab

​Databases

​PostgreSQL

​MySQL

​MongoDB

​API Services

​OpenAI, Anthropic, etc.

​Stripe

​SendGrid, Mailgun

​OAuth Integration

​Supported Providers

​OAuth Flow

​OAuth vs Personal Access Tokens

​Security Best Practices

​Secret Hygiene

​Scope Minimization

​Separation of Environments

​Audit and Monitoring

​Troubleshooting

​Secret Not Working

​OAuth Token Expired

​Permission Denied

​Secret Accidentally Committed

​Integration Patterns

​AWS Deployment Example

​Database Migration Example

​Third-Party API Integration

​Advanced OAuth Patterns

​Multiple GitHub Accounts

​OAuth Secret Sharing

​Next Steps

Secret Management System

What Are Secrets?

Security Model

Managing Secrets

Secret Manager (UI)

Registering Secrets

Activating Secrets

Using Activated Secrets

Deactivating Secrets

Supported Integrations

Cloud Providers

AWS

Azure

Google Cloud Platform

Version Control

GitHub

GitLab

Databases

PostgreSQL

MySQL

MongoDB

API Services

OpenAI, Anthropic, etc.

Stripe

SendGrid, Mailgun

OAuth Integration

Supported Providers

OAuth Flow

OAuth vs Personal Access Tokens

Security Best Practices

Secret Hygiene

Scope Minimization

Separation of Environments

Audit and Monitoring

Troubleshooting

Secret Not Working

OAuth Token Expired

Permission Denied

Secret Accidentally Committed

Integration Patterns

AWS Deployment Example

Database Migration Example

Third-Party API Integration

Advanced OAuth Patterns

Multiple GitHub Accounts

OAuth Secret Sharing

Next Steps