Credential Activation Skill

Configure credentials for skills that require API keys, tokens, or secrets.

Overview

Many skills require external API credentials to function:

notify-user: Mailgun API key and domain
Custom integrations: OpenAI, Anthropic, Stripe, etc.

This skill helps you:

Identify which credentials a skill needs
Check if credentials are already configured
Guide users through the setup process
Verify credentials are working

How Credentials Work in TeamDay

┌─────────────────────────────────────────────────────────┐
│  TeamDay UI (Space Settings > Secrets)                  │
│  User adds: MAILGUN_API_KEY = "key-abc123..."          │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│  Firestore (spaces/{spaceId}/secrets)                   │
│  Encrypted storage                                       │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│  Agent Execution (computer service)                     │
│  Secrets injected as environment variables              │
│  process.env.MAILGUN_API_KEY = "key-abc123..."         │
└─────────────────────────────────────────────────────────┘

Key Points:

Credentials are stored securely in Firestore (not in files)
Injected as environment variables during agent execution
Available to scheduled jobs via the same mechanism
Never stored in plaintext in the space directory

Check Credential Status

Before using a skill that requires credentials, check if they're available:

# Generic check for any credential
check_credential() {
  local var_name=$1
  if [ -n "${!var_name}" ]; then
    echo "✅ $var_name: configured"
    return 0
  else
    echo "❌ $var_name: not configured"
    return 1
  fi
}

# Check multiple credentials
check_credential "MAILGUN_API_KEY"
check_credential "MAILGUN_DOMAIN"
check_credential "NOTIFICATION_EMAIL"

Credential Requirements by Skill

notify-user (Mailgun)

Variable	Required	Description
`MAILGUN_API_KEY`	Yes	Private API key from Mailgun dashboard
`MAILGUN_DOMAIN`	Yes	Verified sending domain
`MAILGUN_REGION`	No	`US` (default) or `EU`
`MAILGUN_FROM_EMAIL`	No	Sender address (defaults to agent@domain)
`NOTIFICATION_EMAIL`	Yes	Default recipient email

Setup Instructions for User:

To configure Mailgun for email notifications:

1. Sign up at https://www.mailgun.com/ (free tier available)

2. Get your API key:
   - Go to Settings > API Keys
   - Copy your "Private API key"

3. Set up a domain (or use sandbox for testing):
   - Go to Sending > Domains
   - Add and verify your domain (follow DNS instructions)
   - Or use the provided sandbox domain for testing

4. In TeamDay:
   - Open your Space settings
   - Go to "Secrets" tab
   - Add the following secrets:

     MAILGUN_API_KEY: your-private-api-key
     MAILGUN_DOMAIN: mg.yourdomain.com
     MAILGUN_REGION: US (or EU if using EU region)
     NOTIFICATION_EMAIL: your-email@example.com

5. For sandbox domains only:
   - Go to Mailgun > Sending > Overview
   - Add your email to "Authorized Recipients"
   - Click the verification link in your email

Custom OpenAI Integration

Variable	Required	Description
`OPENAI_API_KEY`	Yes	OpenAI API key
`OPENAI_ORG_ID`	No	Organization ID (if applicable)

Setup Instructions:

To configure OpenAI API access:

1. Get your API key:
   - Go to https://platform.openai.com/api-keys
   - Create a new API key

2. In TeamDay:
   - Open your Space settings
   - Go to "Secrets" tab
   - Add:

     OPENAI_API_KEY: sk-...your-key...

Custom Anthropic Integration

Variable	Required	Description
`ANTHROPIC_API_KEY`	Yes	Anthropic API key

Setup Instructions:

To configure Anthropic API access:

1. Get your API key:
   - Go to https://console.anthropic.com/
   - Navigate to API Keys
   - Create a new key

2. In TeamDay:
   - Open your Space settings
   - Go to "Secrets" tab
   - Add:

     ANTHROPIC_API_KEY: sk-ant-...your-key...

Activation Workflow

When a skill reports missing credentials, follow this workflow:

Step 1: Identify Required Credentials

# Check skill's SKILL.md for credential requirements
# Look for the metadata.credentials section

Step 2: Check Current Status

# Create a credential check script
check_all_credentials() {
  echo "=== Credential Status ==="
  echo ""

  # Mailgun
  echo "📧 Mailgun (notify-user skill):"
  [ -n "$MAILGUN_API_KEY" ] && echo "  ✅ MAILGUN_API_KEY" || echo "  ❌ MAILGUN_API_KEY"
  [ -n "$MAILGUN_DOMAIN" ] && echo "  ✅ MAILGUN_DOMAIN" || echo "  ❌ MAILGUN_DOMAIN"
  [ -n "$NOTIFICATION_EMAIL" ] && echo "  ✅ NOTIFICATION_EMAIL" || echo "  ❌ NOTIFICATION_EMAIL"
  echo ""

  # OpenAI
  echo "🤖 OpenAI:"
  [ -n "$OPENAI_API_KEY" ] && echo "  ✅ OPENAI_API_KEY" || echo "  ❌ OPENAI_API_KEY"
  echo ""

  # Anthropic
  echo "🧠 Anthropic:"
  [ -n "$ANTHROPIC_API_KEY" ] && echo "  ✅ ANTHROPIC_API_KEY" || echo "  ❌ ANTHROPIC_API_KEY"
}

check_all_credentials

Step 3: Guide User Through Setup

If credentials are missing, provide clear instructions:

🔐 Credential Setup Required

The [skill-name] skill requires the following credentials that are not yet configured:

Missing credentials:
- MAILGUN_API_KEY
- MAILGUN_DOMAIN

To configure these credentials:

1. Open TeamDay in your browser
2. Navigate to this space's settings
3. Click on the "Secrets" tab
4. Add the following secrets:

   MAILGUN_API_KEY: [your Mailgun private API key]
   MAILGUN_DOMAIN: [your verified sending domain]

Need help getting these values? Here's how:
[Include service-specific instructions]

Once configured, restart the agent session to pick up the new credentials.

Step 4: Verify Credentials Work

After user configures credentials, verify they work:

# Mailgun verification
verify_mailgun() {
  if [ -z "$MAILGUN_API_KEY" ] || [ -z "$MAILGUN_DOMAIN" ]; then
    echo "❌ Mailgun credentials not configured"
    return 1
  fi

  # Determine API endpoint
  if [ "$MAILGUN_REGION" = "EU" ]; then
    API="https://api.eu.mailgun.net"
  else
    API="https://api.mailgun.net"
  fi

  # Test API access (list domains)
  RESPONSE=$(curl -s -w "%{http_code}" -o /tmp/mailgun_test.json \
    --user "api:${MAILGUN_API_KEY}" \
    "${API}/v3/domains")

  if [ "$RESPONSE" = "200" ]; then
    echo "✅ Mailgun credentials verified successfully"
    return 0
  else
    echo "❌ Mailgun credential verification failed (HTTP $RESPONSE)"
    cat /tmp/mailgun_test.json
    return 1
  fi
}

verify_mailgun

Creating Credential Documentation

When creating a new skill that requires credentials, document them in the SKILL.md frontmatter:

---
name: my-new-skill
description: ...
metadata:
  requires: credential-activation
  credentials:
    - MY_API_KEY
    - MY_SECRET_TOKEN
---

And include a "Prerequisites" section in the skill:

## Prerequisites

This skill requires the following credentials:

| Variable | Required | Description |
|----------|----------|-------------|
| `MY_API_KEY` | Yes | API key from service dashboard |
| `MY_SECRET_TOKEN` | No | Optional secret for advanced features |

If credentials are not configured, use the `credential-activation` skill to set them up.

Security Best Practices

Never log credentials - Don't echo or print API keys
Never store in files - Use TeamDay's secure storage
Use environment variables - Always access via $VAR_NAME
Rotate regularly - Update keys periodically
Minimum permissions - Request only needed API scopes

Scheduled Jobs and Credentials

Credentials configured in TeamDay are automatically available to scheduled jobs:

Interactive Session    →    Credentials injected from Firestore
Scheduled Job         →    Same credentials injected automatically

No additional setup is needed for scheduled jobs to access credentials that are configured for the space.

Troubleshooting

Credentials configured but not available?

Session needs restart: New credentials are loaded at session start
Wrong space: Credentials are space-specific
Typo in variable name: Check exact spelling in TeamDay UI

Credential verification failing?

Invalid key: Double-check the key value in service dashboard
Expired key: Generate a new key
Wrong region: Some services have regional endpoints
Rate limited: Wait and retry

Scheduled job can't access credentials?

Credentials set after job creation: Re-save the scheduled job
Organization-level vs space-level: Some credentials may be at org level
Check scheduler logs: Look for authentication errors

credential-activation

SKILL.mdskills/teamday/credential-activation/SKILL.md