> ## Documentation Index > Fetch the complete documentation index at: https://meepa.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```yaml theme={null} 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: ```yaml theme={null} 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: ```json theme={null} { "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": "agent-meepa@mg.example.com", "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](/meepachat/integrations/meepagateway#credential-action-cards)) 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 ```http theme={null} 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 ```bash theme={null} meepagateway agent credentials meepa ``` Launches an interactive credential management TUI for the agent. *** ## Removing Credentials ```http theme={null} DELETE /api/captain/agents/{id}/credentials/{category}/{service} ``` Example — remove a GitHub login: ```http theme={null} DELETE /api/captain/agents/meepa/credentials/login/github ``` *** ## Credential Store The credential store uses [SOPS](https://github.com/getsops/sops) with [age](https://github.com/FiloSottile/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: ```yaml theme={null} # 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