How to Integrate and Manage Partners in the Claude API Ecosystem

As the Claude AI ecosystem expands, Anthropic has introduced a Partners feature to facilitate seamless collaboration between developers, organizations, and third-party services. Whether you're building a multi-agent system, integrating Claude into a SaaS platform, or managing API access for a team, understanding the Partners functionality is essential for scaling your AI workflows.

This guide provides a practical, actionable walkthrough of the Partners feature in the Claude API, including setup instructions, code examples, and best practices.

What Is the Partners Feature?

The Partners feature in the Claude API allows you to manage and authenticate multiple entities—such as external applications, team members, or automated services—that interact with your Claude API resources. It provides a structured way to:

• Grant granular permissions to different partners
• Monitor usage and costs per partner
• Rotate credentials without disrupting other integrations
• Enable secure collaboration across teams or organizations

Think of it as a multi-tenant access layer for your Claude API setup. Instead of sharing a single API key, each partner gets its own identity and permissions.

Prerequisites

Before diving into the implementation, ensure you have:

• An active Anthropic account with API access
• A Claude API key (available from the Anthropic Console)
• Basic familiarity with REST APIs and JSON
• Python 3.8+ or Node.js 16+ installed (for code examples)

Setting Up a Partner

Step 1: Create a Partner via the API

To create a new partner, you send a POST request to the /v1/partners endpoint. Here's a Python example using the requests library:

import requests
import os
ANTHROPIC_API_KEY = os.environ.get("ANTHROPIC_API_KEY")
BASE_URL = "https://api.anthropic.com/v1"
headers = {
    "x-api-key": ANTHROPIC_API_KEY,
    "anthropic-version": "2023-06-01",
    "Content-Type": "application/json"
}
partner_data = {
    "name": "My Analytics Dashboard",
    "description": "Internal dashboard for monitoring Claude usage",
    "permissions": ["messages:read", "messages:write"],
    "max_tokens_per_month": 1000000,
    "expires_at": "2025-12-31T23:59:59Z"
}
response = requests.post(
    f"{BASE_URL}/partners",
    headers=headers,
    json=partner_data
)
if response.status_code == 201:
    partner = response.json()
    print(f"Partner created: {partner['id']}")
    print(f"API Key for partner: {partner['api_key']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

Important: The api_key returned in the response is shown only once. Store it securely—you won't be able to retrieve it again.

Step 2: Use the Partner API Key

Once created, the partner can authenticate using its own API key. Here's how a partner would send a message to Claude:

import requests
PARTNER_API_KEY = "sk-ant-partner-..."  # The key from step 1
headers = {
    "x-api-key": PARTNER_API_KEY,
    "anthropic-version": "2023-06-01",
    "Content-Type": "application/json"
}
message_data = {
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Summarize the latest quarterly report."}
    ]
}
response = requests.post(
    "https://api.anthropic.com/v1/messages",
    headers=headers,
    json=message_data
)
print(response.json())

Managing Partners

Listing All Partners

To view all partners associated with your account:

response = requests.get(
    f"{BASE_URL}/partners",
    headers=headers
)
partners = response.json()
for partner in partners["data"]:
    print(f"{partner['id']}: {partner['name']} (Active: {partner['active']})")

Updating a Partner

You can modify permissions, usage limits, or expiration dates:

update_data = {
    "permissions": ["messages:read", "messages:write", "files:read"],
    "max_tokens_per_month": 2000000
}
response = requests.patch(
    f"{BASE_URL}/partners/{partner_id}",
    headers=headers,
    json=update_data
)
print(f"Updated: {response.status_code}")

Deleting a Partner

When a partner is no longer needed, revoke access immediately:

response = requests.delete(
    f"{BASE_URL}/partners/{partner_id}",
    headers=headers
)
if response.status_code == 204:
    print("Partner deleted successfully")
else:
    print(f"Error: {response.status_code}")

Best Practices for Using Partners

1. Use Granular Permissions

Always assign the minimum permissions required. Common permission scopes include:

• messages:read – View message history
• messages:write – Send new messages
• files:read – Access uploaded files
• files:write – Upload files
• admin:read – View partner settings
• admin:write – Modify partner settings

2. Set Usage Limits

Prevent runaway costs by setting max_tokens_per_month for each partner. Monitor usage via the /v1/partners/{id}/usage endpoint:

response = requests.get(
    f"{BASE_URL}/partners/{partner_id}/usage",
    headers=headers
)
usage = response.json()
print(f"Tokens used this month: {usage['tokens_used']}")
print(f"Limit: {usage['tokens_limit']}")

3. Rotate Keys Regularly

For security, rotate partner API keys periodically. Use the /v1/partners/{id}/rotate endpoint:

response = requests.post(
    f"{BASE_URL}/partners/{partner_id}/rotate",
    headers=headers
)
new_key = response.json()["api_key"]
print(f"New API key: {new_key}")

4. Log and Audit

Enable audit logging to track which partner performed which action. Check the /v1/audit-logs endpoint:

response = requests.get(
    f"{BASE_URL}/audit-logs",
    headers=headers,
    params={"partner_id": partner_id, "limit": 10}
)
for log in response.json()["data"]:
    print(f"{log['timestamp']}: {log['action']} by {log['partner_name']}")

Real-World Use Cases

Multi-Agent Systems

If you're building a system where multiple AI agents collaborate (e.g., a research assistant and a summarizer), create a partner for each agent. This allows you to monitor individual agent costs and debug issues independently.

SaaS Integrations

If your platform offers Claude-powered features to end users, create a partner for each customer. This provides per-customer billing and usage analytics.

Team Collaboration

For internal teams, create partners for different departments (e.g., marketing, engineering, support). Set appropriate permissions and limits for each.

Troubleshooting Common Issues

401 Unauthorized

If a partner receives a 401 error, their API key may be expired or revoked. Check the partner's expires_at field and rotate the key if needed.

429 Rate Limited

Each partner has its own rate limit. If a partner hits this limit, consider increasing their max_tokens_per_month or implementing retry logic with exponential backoff.

Partner Not Found

Ensure you're using the correct partner ID. Partner IDs start with partner_ and are case-sensitive.

Conclusion

The Partners feature in the Claude API is a powerful tool for managing multi-tenant access, enhancing security, and scaling your AI integrations. By following the steps and best practices outlined in this guide, you can efficiently manage multiple entities interacting with Claude while maintaining control over permissions, costs, and security.

Start by creating a test partner, experiment with different permission levels, and gradually roll out to your production environment. The flexibility of the Partners API makes it suitable for everything from small team projects to large-scale enterprise deployments.

Key Takeaways

• Granular Access Control: Use the Partners feature to assign specific permissions (read, write, admin) to each entity, reducing security risks.
• Cost Management: Set per-partner token limits and monitor usage to prevent unexpected bills and allocate resources effectively.
• Secure Key Rotation: Regularly rotate partner API keys using the dedicated endpoint without affecting other integrations.
• Audit and Compliance: Leverage audit logs to track partner actions, ensuring accountability and meeting compliance requirements.
• Scalable Architecture: Design your system with partners from the start to easily add new integrations, agents, or team members as your Claude usage grows.