---
title: "使用 API Key 进行出站认证"
---

API Key 是最简单的出站认证方式，适用于固定凭证、服务间通信的场景。凭据由 Agent Identity 加密托管，不出现在代码中。本页只讲 API Key 特有的部分；`VeIdentityFunctionTool` / `VeIdentityMcpToolset` 的通用用法、`into` 默认值与常见问题见[安全概述](/cn/docs/framework/security#出站认证)。

## 创建 API Key 凭据

1. 登录火山引擎控制台，进入 **Agent Identity** 服务。
2. 选择 **身份认证 > 出站凭据托管**。
3. 点击 **新建 > 新建 API Key**，填写名称。
4. 输入第三方服务提供的 API Key。
5. 选择传递方式（Header 或 Query）并点击 **确定**。

## 在代码中使用

用 `api_key_auth(provider_name=...)` 创建认证配置，传给 `VeIdentityFunctionTool` 或 `VeIdentityMcpToolset`。API Key 凭据默认注入到函数的 `api_key` 参数（`into` 的默认值），调用时无需自己传入：

```python
import asyncio
from veadk import Agent, Runner
from veadk.integrations.ve_identity import VeIdentityFunctionTool, api_key_auth
import aiohttp

async def query_api(api_key: str, user_id: str):
    headers = {"Authorization": f"Bearer {api_key}"}
    url = f"https://api.example.com/users/{user_id}"
    async with aiohttp.ClientSession() as session:
        async with session.get(url, headers=headers) as resp:
            return await resp.json()

tool = VeIdentityFunctionTool(
    func=query_api,
    auth_config=api_key_auth(provider_name="user-api"),
)

agent = Agent(tools=[tool])
runner = Runner(agent=agent)
asyncio.run(runner.run(messages="查询用户 123"))
```

封装整个 MCP 服务时换用 `VeIdentityMcpToolset`，传入同一个 `api_key_auth` 配置：

```python
from veadk.integrations.ve_identity import VeIdentityMcpToolset, api_key_auth
from mcp import StdioServerParameters

toolset = VeIdentityMcpToolset(
    auth_config=api_key_auth(provider_name="my-api-provider"),
    connection_params=StdioServerParameters(
        command="python",
        args=["-m", "my_api_mcp_server"],
    ),
)
```

## 何时选 API Key

API Key 凭证固定、用法最简单，适合无需令牌刷新的场景。需要短期令牌与自动刷新时改用 [OAuth2 M2M](/cn/docs/framework/oauth2-m2m)；需代表某个用户访问时改用 [OAuth2 用户委托](/cn/docs/framework/oauth2-user-federation)。
