> ## Documentation Index
> Fetch the complete documentation index at: https://docs.igent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**:

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**:

```bash theme={null}
# 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**:

```bash theme={null}
# 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**:

```bash theme={null}
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**:

```bash theme={null}
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**:

```bash theme={null}
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:

* **[Troubleshooting](../reference/troubleshooting)**: Common issues and solutions
* **[FAQ](../reference/faq)**: Frequently asked questions
* **[Best Practices](../reference/best-practices)**: Production-ready patterns
* **[Billing](../reference/billing)**: Understanding costs and plans