Multi-Account

TAP supports multi-account access — a single agent can use credentials from multiple teams. This lets one agent access both personal API keys and company-managed credentials without needing separate API keys for each team.

Use Case

A developer has a personal team with their own API keys (OpenAI, GitHub) and works at a company that manages production credentials (Slack, Twitter, internal APIs). They want one agent to use both sets of credentials seamlessly.

Without multi-account, the developer would need two separate agents with two separate API keys. With multi-account, a single agent authenticates once and uses the X-TAP-Team header to switch between teams.

How It Works

Multi-account access is powered by the agent_team_links table. When a team admin links an external agent into their team, that agent gains access to the team’s credentials — scoped by an optional role.

The key concepts:

• Home team — the team where the agent was originally created. This is the default when no X-TAP-Team header is sent.
• Linked team — a team that has invited the agent in. The agent can access credentials in this team by specifying its team ID in the X-TAP-Team header.
• Role scope — the linking admin can optionally restrict the linked agent to a specific role, limiting which credentials it can access in the linked team.

Setup Flow

1. Developer Creates a Personal Team and Agent

# Sign up
curl -X POST $PROXY_URL/signup \
  -H "Content-Type: application/json" \
  -d '{"team_name": "alice-personal", "email": "alice@example.com", "password": "password123"}'
 
# (verify email, login)
 
# Create agent
curl -X POST $PROXY_URL/admin/agents \
  -H "Authorization: Bearer $ALICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "alice-agent",
    "description": "Alice personal agent",
    "credentials": ["openai", "github"]
  }'
 
# Save the agent API key
export AGENT_KEY="<api_key from response>"

At this point, Alice’s agent can use openai and github credentials from her personal team.

2. Company Admin Creates Company Team and Credentials

# (company admin signs up, verifies, logs in)
 
# Add company credentials
curl -X POST $PROXY_URL/admin/credentials \
  -H "Authorization: Bearer $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "slack", "description": "Company Slack", "value": "xoxb-company-token"}'
 
curl -X POST $PROXY_URL/admin/credentials \
  -H "Authorization: Bearer $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "twitter", "description": "Company Twitter", "value": "bearer-token"}'
 
# Create a role for linked agents
curl -X POST $PROXY_URL/admin/roles \
  -H "Authorization: Bearer $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "social-poster", "credentials": ["slack", "twitter"]}'

3. Company Admin Links Alice’s Agent

The company admin invites Alice’s agent into the company team, scoped to the social-poster role:

curl -X POST $PROXY_URL/admin/agent-links \
  -H "Authorization: Bearer $COMPANY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_home_team_id": "<alice-personal-team-id>",
    "agent_id": "alice-agent",
    "role": "social-poster"
  }'

The agent_home_team_id is the team ID where Alice’s agent was created. The company admin needs this ID to create the link. The linked team (the company) is automatically set to the admin’s own team.

4. Agent Uses Cross-Team Credentials

Alice’s agent uses its single API key for both teams. For the home team, no extra header is needed:

# Use personal OpenAI credential (home team, no X-TAP-Team needed)
curl -X POST $PROXY_URL/forward \
  -H "X-TAP-Key: $AGENT_KEY" \
  -H "X-TAP-Credential: openai" \
  -H "X-TAP-Target: https://api.openai.com/v1/models" \
  -H "X-TAP-Method: GET"

For the company team, add the X-TAP-Team header:

# Use company Slack credential (linked team)
curl -X POST $PROXY_URL/forward \
  -H "X-TAP-Key: $AGENT_KEY" \
  -H "X-TAP-Team: <company-team-id>" \
  -H "X-TAP-Credential: slack" \
  -H "X-TAP-Target: https://slack.com/api/chat.postMessage" \
  -H "X-TAP-Method: POST" \
  -H "Content-Type: application/json" \
  -d '{"channel": "C123", "text": "Hello from multi-account"}'

Managing Links

List Agent Links

View all agents linked into your team:

curl $PROXY_URL/admin/agent-links \
  -H "Authorization: Bearer $COMPANY_TOKEN"

Remove a Link

curl -X DELETE $PROXY_URL/admin/agent-links/<home-team-id>/alice-agent \
  -H "Authorization: Bearer $COMPANY_TOKEN"

The agent immediately loses access to the company team’s credentials.

Security Model

Multi-account access is designed with least privilege:

• Linking grants access, not visibility. A linked agent can use credentials through the proxy but never sees their values. The company’s secrets remain encrypted and isolated.
• Role scoping limits exposure. If the link specifies a role, the agent can only access credentials in that role — not all credentials in the team.
• No role = no credentials. If the link specifies no role and the agent has no direct credential assignments in the linked team, it has access to nothing. (In practice, links should always specify a role.)
• Each team controls its own links. The company admin creates and removes links. The agent’s home team admin has no control over what the company team exposes.
• Policies still apply. The linked team’s policies govern approval behavior. If the company requires Telegram approval for Slack POST requests, that applies to linked agents too.
• Audit trail is team-scoped. Requests using company credentials are logged in the company’s audit trail, regardless of which team the agent belongs to.

The X-TAP-Team Header

When the header is present, the proxy checks whether the agent has a link to the specified team. If not, the request is rejected with 403. If linked, the proxy resolves credentials, policies, and audit logging against the target team.

Discovering Available Teams

Agents can check which teams they have access to via the service discovery endpoint:

curl $PROXY_URL/agent/services \
  -H "X-TAP-Key: $AGENT_KEY"

The response includes information about available credentials and their teams.