Credentials

Credentials Overview

Securely store and manage API keys, tokens, and secrets used by your tools and integrations.

What are Credentials?

Credentials provide secure storage for API keys, tokens, and other secrets that your tools need to access external services. When a tool requires authentication to interact with a third-party API, it references a credential rather than storing the secret directly.

Agent Dojo encrypts all credential data at rest and never returns secrets in API responses. This ensures your sensitive information remains protected while still being available to your tools at runtime.

Creating Credentials

Store a new credential by providing a name, the provider it belongs to, and the secret data:

curl -X POST https://api.agentdojo.dev/mcp/credentials \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenAI Production Key",
    "provider_id": "provider_openai_001",
    "credential_data": {
      "api_key": "sk-proj-abc123..."
    }
  }'

Response:

{
  "id": "cred_001",
  "name": "OpenAI Production Key",
  "provider_id": "provider_openai_001",
  "created_at": "2026-01-15T10:30:00Z"
}

Important: The credential_data field is write-only. It is never returned in any API response after creation.

Listing Credentials

Retrieve all stored credentials. Secrets are never included in the response:

curl -X GET https://api.agentdojo.dev/mcp/credentials \
  -H "X-API-Key: your-api-key"

Response:

{
  "credentials": [
    {
      "id": "cred_001",
      "name": "OpenAI Production Key",
      "provider_id": "provider_openai_001",
      "created_at": "2026-01-15T10:30:00Z"
    },
    {
      "id": "cred_002",
      "name": "Slack Bot Token",
      "provider_id": "provider_slack_001",
      "created_at": "2026-01-16T14:00:00Z"
    }
  ]
}

Deleting Credentials

Remove a stored credential by its ID:

curl -X DELETE https://api.agentdojo.dev/mcp/credentials/cred_001 \
  -H "X-API-Key: your-api-key"

Warning: Deleting a credential will break any tools that depend on it. Make sure no active tools reference this credential before deleting.

Credential Providers

Providers define the authentication method used by a credential. List available providers to see which authentication types are supported:

curl -X GET https://api.agentdojo.dev/mcp/providers \
  -H "X-API-Key: your-api-key"

Supported provider types:

Type	Description	Example Use Case
oauth	OAuth 2.0 authorization flow	Google, GitHub, Slack integrations
api_key	Static API key authentication	OpenAI, Stripe, SendGrid
basic_auth	HTTP Basic authentication (username/password)	Legacy APIs, SMTP services
custom	Custom authentication scheme	Proprietary APIs with unique auth
none	No authentication required	Public APIs, open data sources

How Tools Use Credentials

Tools reference credentials through a two-step mapping:

Tool declares a credential provider

When registering a tool, you specify which credential_provider it requires (e.g., "openai" or "slack").

Server maps credential to tool

When adding a toolkit to a server, you map a stored credential_id to the tool's required provider. At runtime, Agent Dojo securely injects the credential data into the tool invocation.

// Adding a toolkit to a server with credential mapping
{
  "toolkit_id": "tk_openai_001",
  "credentials": {
    "openai": "cred_001"  // Maps the "openai" provider to credential cred_001
  }
}