Credentials

Provision and store real-world credentials for agents: email, phone, credit card, logins, API keys, and more

Overview

MeepaGateway manages credentials for your agents using a flat credential model. All credential types — email addresses, phone numbers, virtual credit cards, GitHub tokens, and custom logins — are stored as uniform AgentCredential entries grouped by category.

Credentials are provisioned per-agent. Built-in categories (email, phone, credit card) support automatic provisioning through external services. Other categories (login, api_key) are stored directly with no provisioning step required.

Credentials are stored in a SOPS-encrypted file in each agent’s workspace.

Credential provisioning is disabled by default. Enable it under credentials in config.yaml.

---

Credential Categories

Category	Provisioned?	Example Services
email	Yes (automatic)	AgentMail, Google Workspace
phone	No (manual)	Tello, carrier SIMs
credit_card	Yes (automatic)	Privacy.com, manual entry
login	No (stored directly)	GitHub, npm, Stripe
api_key	No (stored directly)	OpenAI, Anthropic, custom
token	No (stored directly)	OAuth tokens, JWTs

---

Credential Origins

Every credential has an origin that tracks how it was obtained:

• operator_provided — An operator or admin pre-created and registered the credential.
• agent_created — The agent autonomously created this credential (e.g., signed up for a service using its email address).

---

Configuration

Global Setup

credentials:
  enabled: true

  credential_store:
    provider: sops   # "sops" (default) or "none"
    sops:
      # Public key for age encryption (auto-generated if absent)
      # public_key: "age1..."
      # Path to private key file (default: ~/.meepagateway/agents/{id}/private-key.key)
      # key_file: /path/to/key.key

  email:
    enabled: true
    provider: agentmail   # "agentmail", "google_workspace", or "existing"
    agentmail:
      api_key_env: AGENTMAIL_API_KEY
      # domain: yourdomain.com   # optional custom domain

  phone:
    enabled: false   # Enable to allow per-agent phone number overrides

  credit_card:
    enabled: true
    provider: privacy_com   # "privacy_com" or "manual"
    privacy_com:
      api_key_env: PRIVACY_API_KEY
      default_spend_limit: 5000       # cents ($50.00)
      default_spend_limit_duration: MONTHLY
      card_type: MERCHANT_LOCKED

Per-Agent Override

Disable or customise credentials for a specific agent:

agents:
  - id: meepa
    identity:
      enabled: false   # Disable provisioning for this agent
      email_prefix: custom-prefix   # Override email prefix
      credit_card_spend_limit: 2000 # Override spend limit (cents)

---

Credential File Format

Provisioned credentials are written to:

~/.meepagateway/agents/{agent_id}/credentials.json

The file uses a flat list format:

{
  "credential_store": {
    "provider": "sops",
    "item_id": "meepa-credentials",
    "vault": "agents",
    "status": "provisioned"
  },
  "credentials": [
    {
      "category": "email",
      "service": "agentmail",
      "name": "Email",
      "origin": "operator_provided",
      "items": [
        { "key": "address", "value": "[e-mail]", "item_type": "email" },
        { "key": "inbox_id", "value": "abc123", "item_type": "other" }
      ],
      "status": "provisioned"
    },
    {
      "category": "credit_card",
      "service": "privacy_com",
      "name": "Credit Card",
      "origin": "operator_provided",
      "items": [
        { "key": "last_four", "value": "1234", "item_type": "other" }
      ],
      "metadata": { "spend_limit": 5000 },
      "status": "provisioned"
    },
    {
      "category": "login",
      "service": "github",
      "name": "GitHub",
      "origin": "operator_provided",
      "items": [
        { "key": "token", "value": "ghp_xxx", "item_type": "api_token" }
      ],
      "status": "existing"
    }
  ],
  "provisioned_at": "2025-07-01T09:00:00Z"
}

Old identity.json files are automatically migrated to this format on first read.

---

Action Cards (Chat-Based Credential Storage)

Agents can store credentials through interactive action cards in chat. When an agent calls the credential tool with add_credential, it sends a form to the conversation where the user fills in the service name, username, password, and confirms. The credential is then encrypted and saved.

Action cards are currently supported on MeepaChat. To enable them:

1. Add a meepachat connector to the agent
2. Set gateway_api_url in MeepaChat’s config (see MeepaChat integration guide)

Action cards expire after 5 minutes. Only one pending action per agent is allowed — creating a new one replaces any existing action.

---

Adding Login / API Key Credentials

Login and API key credentials do not require provisioning — they are stored directly in the agent’s encrypted credential store.

Via the Captain Dashboard

1. Open the agent in the Captain dashboard.
2. Scroll to Agent Credentials and click + Add Credential.
3. Select a category (Login, API Key, Token), enter the service name and value, and save.

Via the API

POST /api/captain/agents/{id}/credentials
Content-Type: application/json

{
  "category": "login",
  "service": "github",
  "name": "GitHub",
  "origin": "operator_provided",
  "items": [
    { "key": "token", "value": "ghp_xxx", "item_type": "api_token" }
  ]
}

Via the CLI

meepagateway agent credentials meepa

Launches an interactive credential management TUI for the agent.

---

Removing Credentials

DELETE /api/captain/agents/{id}/credentials/{category}/{service}

Example — remove a GitHub login:

DELETE /api/captain/agents/meepa/credentials/login/github

---

Credential Store

The credential store uses SOPS with age encryption. An age keypair is generated automatically on first provisioning:

~/.meepagateway/agents/{agent_id}/private-key.key   # private key (back this up)

All credential values are encrypted at rest. Plaintext credentials never touch disk outside of the credential store.

---

Container Injection

When inject_credentials_env = true, the agent’s credentials are injected as environment variables into the Docker container:

# Per-agent config
agents:
  - id: meepa
    image_config:
      inject_credentials_env: true
      inject_secrets_env: true

Available environment variables inside the container:

Variable	Source
AGENT_EMAIL	Provisioned email address
AGENT_PHONE	Provisioned phone number
AGENTMAIL_API_KEY	AgentMail API key
PRIVACY_API_KEY	Privacy.com API key

---

Credential Status Values

Each AgentCredential entry has a status field:

Status	Meaning
provisioned	Resource was newly created by this run
existing	Resource already existed and was reused
pending_manual	Waiting for manual action (e.g. SIM card activation)
pending_signup	Agent is in the process of signing up autonomously
skipped	Credential type not configured or disabled
{ "failed": "reason" }	Provisioning failed with the given reason

Partial success is valid — the credentials file is written even if some entries fail.

---

Security Notes

• Back up private-key.key — without it, credentials cannot be decrypted
• Credential values are encrypted at rest via SOPS/age
• inject_credentials_env = true passes credentials into container env — only enable when the agent’s tools require them
• Deprovisioning deletes the local credentials file but does not revoke credentials in third-party services (Privacy.com cards, AgentMail inboxes, etc.) — revoke those manually