托管智能体的凭据
凭证是服务器管理的机密,可让您的智能体访问第三方服务,而无需机密进入智能体的环境。您存储凭证一次,通过 ID 引用它,然后出口代理会在请求时解析并注入它。
秘密值是只写的。一旦存储,它们就不会被任何端点返回,因此受损的智能体无法读回它正在使用的 token。
您使用凭据的主要位置是网络白名单 environment.network。首先存储秘密:
from google import genai
client = genai.Client(http_options={"api_version": "v1beta"})
credential = client.credentials.create(
id="github-production",
type="bearer_token",
token="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
)
print(f"Credential ID: {credential.id}, Status: {credential.status}")
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });
const credential = await client.credentials.create({
id: "github-production",
type: "bearer_token",
token: "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
});
console.log(`Credential ID: ${credential.id}, Status: ${credential.status}`);
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/credentials"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
if err != nil {
log.Fatal(err)
}
res, err := client.Credentials.Create(ctx, operations.CreateCredentialRequest{
Body: credentials.NewCredentialCreateParams(credentials.HTTPBearerConfig{
ID: "github-production",
Token: "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Credential ID: %s, Status: %v\n", res.Credential.ID, res.Credential.GetStatus())
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"id": "github-production",
"type": "bearer_token",
"token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}'
gemini-api credentials create --body '{
"id": "github-production",
"type": "bearer_token",
"token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}'
然后将其附加到它验证的域:
interaction = client.interactions.create(
agent="antigravity-preview-09-2026",
input="Triage the open issues in my-org/my-repo.",
environment={
"type": "remote",
"network": {
"allowlist": [
{"domain": "api.github.com", "credential": "github-production"},
{"domain": "*"},
]
},
},
)
const interaction = await client.interactions.create({
agent: "antigravity-preview-09-2026",
input: "Triage the open issues in my-org/my-repo.",
environment: {
type: "remote",
network: {
allowlist: [
{ domain: "api.github.com", credential: "github-production" },
{ domain: "*" },
],
},
},
});
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Triage the open issues in my-org/my-repo."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(interactions.Environment{
Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
{Domain: "api.github.com", Credential: genai.Ptr("github-production")},
{Domain: "*"},
})),
})),
})),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Println(res.Interaction.GetOutputText())
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"agent": "antigravity-preview-09-2026",
"input": "Triage the open issues in my-org/my-repo.",
"environment": {
"type": "remote",
"network": {
"allowlist": [
{ "domain": "api.github.com", "credential": "github-production" },
{ "domain": "*" }
]
}
}
}'
gemini-api agent run "Triage the open issues in my-org/my-repo." \
--agent antigravity-preview-09-2026 \
--body '{
"environment": {
"type": "remote",
"network": {"allowlist": [
{"domain": "api.github.com", "credential": "github-production"},
{"domain": "*"}
]}
}
}'
智能体现在发出经过身份验证的请求 api.github.com,并且 token 永远不会存在于沙箱内。
凭证类型 #
每个凭证都有一个 type 这决定了它接受哪些字段以及代理如何应用它。
| 类型 | 使用案例 | 行为 |
|---|---|---|
bearer_token | 个人访问 token、机器人 token、静态 API 密钥 | 代理注入 token 作为请求标头。没有刷新逻辑。 |
oauth2 | OAuth 应用程序和用户委托流 | 代理将刷新 token 交换为访问 token,并在它们过期时刷新它们。 |
environment_variable | 从流程环境读取机密的客户端 SDK | 智能体的环境接收一个占位符。代理替换出站请求上的真实机密。 |
使用网络白名单中的凭据 #
添加 credential 到允许列表规则,并且代理验证对该域的每个出站请求。这是授予智能体访问私有 API、私有存储库或私有存储桶的推荐方法。
您可以在同一允许列表中混合经过身份验证和未经身份验证的规则:
interaction = client.interactions.create(
agent="antigravity-preview-09-2026",
input="Sync the open Jira issues into the tracking sheet in my repo.",
environment={
"type": "remote",
"sources": [
{
"type": "repository",
"source": "https://github.com/your-org/backend",
"target": "/backend-app",
}
],
"network": {
"allowlist": [
{"domain": "github.com", "credential": "github-production"},
{"domain": "api.atlassian.com", "credential": "jira-oauth"},
{"domain": "*.googleapis.com"},
]
},
},
)
const interaction = await client.interactions.create({
agent: "antigravity-preview-09-2026",
input: "Sync the open Jira issues into the tracking sheet in my repo.",
environment: {
type: "remote",
sources: [
{
type: "repository",
source: "https://github.com/your-org/backend",
target: "/backend-app",
},
],
network: {
allowlist: [
{ domain: "github.com", credential: "github-production" },
{ domain: "api.atlassian.com", credential: "jira-oauth" },
{ domain: "*.googleapis.com" },
],
},
},
});
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Sync the open Jira issues into the tracking sheet in my repo."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(interactions.Environment{
Sources: []interactions.Source{
{
Type: interactions.SourceTypeRepository.ToPointer(),
Source: genai.Ptr("https://github.com/your-org/backend"),
Target: genai.Ptr("/backend-app"),
},
},
Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
{Domain: "github.com", Credential: genai.Ptr("github-production")},
{Domain: "api.atlassian.com", Credential: genai.Ptr("jira-oauth")},
{Domain: "*.googleapis.com"},
})),
})),
})),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Println(res.Interaction.GetOutputText())
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"agent": "antigravity-preview-09-2026",
"input": "Sync the open Jira issues into the tracking sheet in my repo.",
"environment": {
"type": "remote",
"sources": [
{
"type": "repository",
"source": "https://github.com/your-org/backend",
"target": "/backend-app"
}
],
"network": {
"allowlist": [
{ "domain": "github.com", "credential": "github-production" },
{ "domain": "api.atlassian.com", "credential": "jira-oauth" },
{ "domain": "*.googleapis.com" }
]
}
}
}'
由于代理会解析每个请求的凭据,因此 oauth2 凭证透明地刷新其访问 token。当访问 token 过期时,长时间运行的交互不会中断。
组合 credential 和 transform #
允许列表规则也接受内联 transform 直接在规则上设置标题的对象。这两种机制均由线路上的出口代理应用,因此在这两种情况下,标头值永远不会存在于沙箱内。这两个字段可以出现在同一条规则中。
| 规则配置 | 行为 |
|---|---|
credential 仅 | 代理解析凭据并将其标头注入到域的每个请求中。 |
transform 仅 | 静态标头注入。您编写的标头将按原样发送。 |
| 两者都 | 首先应用凭证,然后 transform 合并在顶部。明确的 transform 如果两者设置相同的密钥,则 header 获胜。 |
| 两者都没有 | 允许该域,并且不会注入任何标头。 |
当您想要存储一次机密并从项目中的每个环境、智能体和触发器引用它时,以及当您想要访问为您处理的 token 刷新和旋转时,值得使用凭证。内联 transform 当该值属于单个调用时适合,例如您在创建交互之前自己生成的 token。
将两者结合起来是很常见的。凭证携带身份验证标头和 transform 添加上游服务对同一请求期望的其他内容:
{
"domain": "api.atlassian.com",
"credential": "jira-oauth",
"transform": {
"X-Atlassian-Workspace": "my-workspace-id"
}
}
将秘密移出内联 transform 并存入凭证,将其存储为 POST /credentials,替换 auth 标头 transform 使用 "credential": "<id>",并留下其余的 transform 单独对象。
将凭证与 MCP 服务器一起使用 #
远程MCP服务器采取相同的 credential 场。将其设置在 mcp_server 工具和代理将 auth 标头注入到对该服务器的每个请求中:
interaction = client.interactions.create(
agent="antigravity-preview-09-2026",
input="Create a new issue in my-org/my-repo",
environment="remote",
tools=[{
"type": "mcp_server",
"name": "github",
"url": "https://api.githubcopilot.com/mcp",
"credential": "github-production",
}],
)
const interaction = await client.interactions.create({
agent: "antigravity-preview-09-2026",
input: "Create a new issue in my-org/my-repo",
environment: "remote",
tools: [{
type: "mcp_server",
name: "github",
url: "https://api.githubcopilot.com/mcp",
credential: "github-production",
}],
});
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Create a new issue in my-org/my-repo"),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(interactions.Environment{
Network: genai.Ptr(interactions.NewNetwork(interactions.EnvironmentNetworkEgressAllowlist{
Allowlist: genai.Ptr(interactions.NewAllowlist([]interactions.AllowlistEntry{
{Domain: "api.githubcopilot.com", Credential: genai.Ptr("github-production")},
})),
})),
})),
Tools: []interactions.Tool{
interactions.NewTool(interactions.MCPServer{
Name: genai.Ptr("github"),
URL: genai.Ptr("https://api.githubcopilot.com/mcp"),
}),
},
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Println(res.Interaction.GetOutputText())
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"agent": "antigravity-preview-09-2026",
"input": "Create a new issue in my-org/my-repo",
"environment": "remote",
"tools": [
{
"type": "mcp_server",
"name": "github",
"url": "https://api.githubcopilot.com/mcp",
"credential": "github-production"
}
]
}'
credential 和 headers 遵循与白名单相同的优先规则。首先应用凭证,然后 headers 合并在顶部,因此如果两者设置相同的键,则显式标头获胜:
{
"type": "mcp_server",
"name": "jira",
"url": "https://jira.atlassian.com/mcp",
"credential": "jira-oauth",
"headers": {
"X-Atlassian-Workspace": "my-workspace-id"
}
}
将秘密移出内联 headers 并存入凭证,将其存储为 POST /credentials 并替换 auth 条目 headers 使用 credential。将其他标题保留在原来的位置。
使用凭据作为环境变量 #
某些客户端库从进程环境中读取机密,而不是接受它们作为请求标头。套接字模式和长轮询客户端是常见情况。
绑定一个 environment_variable 下变量名的凭证 environment.env:
interaction = client.interactions.create(
agent="antigravity-preview-09-2026",
input="Run the sync script and check notifications.",
environment={
"type": "remote",
"env": {
"NODE_ENV": "production",
"SLACK_BOT_TOKEN": {"credential": "slack-bot-token"},
},
},
)
const interaction = await client.interactions.create({
agent: "antigravity-preview-09-2026",
input: "Run the sync script and check notifications.",
environment: {
type: "remote",
env: {
NODE_ENV: "production",
SLACK_BOT_TOKEN: { credential: "slack-bot-token" },
},
},
});
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Run the sync script and check notifications."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(interactions.Environment{
Env: genai.Ptr(interactions.NewEnv(map[string]interactions.EnvVar{
"NODE_ENV": {Value: genai.Ptr("production")},
"SLACK_BOT_TOKEN": {Credential: genai.Ptr("slack-bot-token")},
})),
})),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Println(res.Interaction.GetOutputText())
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"agent": "antigravity-preview-09-2026",
"input": "Run the sync script and check notifications.",
"environment": {
"type": "remote",
"env": {
"NODE_ENV": "production",
"SLACK_BOT_TOKEN": { "credential": "slack-bot-token" }
}
}
}'
gemini-api agent run "Run the sync script and check notifications." \
--agent antigravity-preview-09-2026 \
--body '{
"environment": {
"type": "remote",
"env": {"NODE_ENV": "production", "SLACK_BOT_TOKEN": {"credential": "slack-bot-token"}}
}
}'
env 并排接受文字字符串和凭据引用。文字字符串作为普通的明文变量注入到容器中。
凭证参考则不然。变量接收占位符 __GEMINI_CRED_<credential-id>__,并且代理仅针对前往凭证中的域的出站请求交换真正的秘密 trusted_domains。对任何其他域的请求都会被拒绝,因此秘密永远不会离开边界,并且占位符也不会发送到其位置。
注意:文字值以纯文本形式注入,并且可由沙箱中运行的任何内容读取,包括智能体本身。使用它们进行配置,例如 NODE_ENV,不是为了秘密。秘密属于凭证,这是获得占位符和在线替换的唯一形式。
套装 trusted_domains 在每一个 environment_variable 凭证。它是对可以使用秘密的范围的控制。
创建凭证 #
每个创建请求都需要一个 type,加上该类型所需的任何字段。
直接调用REST时,所有字段名称都使用snake_case。发送驼峰命名法字段返回 400.
承载token #
只需持有token凭证 token:
credential = client.credentials.create(
id="github-production",
type="bearer_token",
token="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
)
const credential = await client.credentials.create({
id: "github-production",
type: "bearer_token",
token: "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
});
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/credentials"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
if err != nil {
log.Fatal(err)
}
res, err := client.Credentials.Create(ctx, operations.CreateCredentialRequest{
Body: credentials.NewCredentialCreateParams(credentials.HTTPBearerConfig{
ID: "github-production",
Token: "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Created credential: %s\n", res.Credential.ID)
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"id": "github-production",
"type": "bearer_token",
"token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}'
gemini-api credentials create --body '{
"id": "github-production",
"type": "bearer_token",
"token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}'
响应仅返回元数据,从不返回 token:
{
"id": "github-production",
"type": "bearer_token",
"status": "active",
"create_time": "2026-07-15T10:00:00.000000000Z",
"update_time": "2026-07-15T10:00:00.000000000Z"
}
默认情况下,代理发送 Authorization: Bearer <token>。覆盖 header_name 和 prefix 以期望其他内容的服务为目标:
credential = client.credentials.create(
id="my-api-key",
type="bearer_token",
token="key_xxxxxxxxxxxx",
header_name="x-goog-api-key",
prefix="",
)
const credential = await client.credentials.create({
id: "my-api-key",
type: "bearer_token",
token: "key_xxxxxxxxxxxx",
header_name: "x-goog-api-key",
prefix: "",
});
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/credentials"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
if err != nil {
log.Fatal(err)
}
res, err := client.Credentials.Create(ctx, operations.CreateCredentialRequest{
Body: credentials.NewCredentialCreateParams(credentials.HTTPBearerConfig{
ID: "my-api-key",
Token: "key_xxxxxxxxxxxx",
HeaderName: genai.Ptr("x-goog-api-key"),
Prefix: genai.Ptr(""),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Created credential: %s\n", res.Credential.ID)
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"id": "my-api-key",
"type": "bearer_token",
"token": "key_xxxxxxxxxxxx",
"header_name": "x-goog-api-key",
"prefix": ""
}'
gemini-api credentials create --body '{
"id": "my-api-key",
"type": "bearer_token",
"token": "key_xxxxxxxxxxxx",
"header_name": "x-goog-api-key",
"prefix": ""
}'
此配置生成标头 x-goog-api-key: key_xxxxxxxxxxxx.
下表显示了如何 header_name 和 prefix 结合:
| 配置 | 注入头 |
|---|---|
{"token": "ghp_xxx"} | Authorization: Bearer ghp_xxx |
{"token": "sk_live_xxx"} | Authorization: Bearer sk_live_xxx |
{"token": "key_xxx", "header_name": "x-goog-api-key", "prefix": ""} | x-goog-api-key: key_xxx |
{"token": "mytoken", "header_name": "X-API-Token", "prefix": ""} | X-API-Token: mytoken |
OAuth2 #
OAuth2 凭证需要 client_id, client_secret, refresh_token, 和 token_url。的 scopes 字段是可选的:
credential = client.credentials.create(
id="jira-oauth",
type="oauth2",
client_id="my-client-id",
client_secret="my-client-secret",
token_url="https://auth.atlassian.com/oauth/token",
refresh_token="rt_xxxxxxxxxxxxxxxxxxxx",
scopes=["read:jira-work", "write:jira-work"],
)
const credential = await client.credentials.create({
id: "jira-oauth",
type: "oauth2",
client_id: "my-client-id",
client_secret: "my-client-secret",
token_url: "https://auth.atlassian.com/oauth/token",
refresh_token: "rt_xxxxxxxxxxxxxxxxxxxx",
scopes: ["read:jira-work", "write:jira-work"],
});
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/credentials"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
if err != nil {
log.Fatal(err)
}
res, err := client.Credentials.Create(ctx, operations.CreateCredentialRequest{
Body: credentials.NewCredentialCreateParams(credentials.OAuth2Config{
ID: "jira-oauth",
ClientID: "my-client-id",
ClientSecret: "my-client-secret",
TokenURL: "https://auth.atlassian.com/oauth/token",
RefreshToken: "rt_xxxxxxxxxxxxxxxxxxxx",
Scopes: []string{"read:jira-work", "write:jira-work"},
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Created OAuth2 credential: %s\n", res.Credential.ID)
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"id": "jira-oauth",
"type": "oauth2",
"client_id": "my-client-id",
"client_secret": "my-client-secret",
"token_url": "https://auth.atlassian.com/oauth/token",
"refresh_token": "rt_xxxxxxxxxxxxxxxxxxxx",
"scopes": ["read:jira-work", "write:jira-work"]
}'
gemini-api credentials create --body '{
"id": "jira-oauth",
"type": "oauth2",
"client_id": "my-client-id",
"client_secret": "my-client-secret",
"token_url": "https://auth.atlassian.com/oauth/token",
"refresh_token": "rt_xxxxxxxxxxxxxxxxxxxx",
"scopes": ["read:jira-work", "write:jira-work"]
}'
创建 OAuth2 凭证执行实时 token 交换 token_url 确认配置有效。仅当提供者返回包含以下内容的成功 token 响应时,才会存储凭证 access_token。 JSON 和表单 urlencoded 响应均被接受。
这意味着您在创建时需要有效的、未过期的刷新 token。如果提供商拒绝交换,则会向您返回错误:
{
"error": {
"message": "OAuth token validation failed with HTTP 403: {\"error\":\"unauthorized_client\",\"error_description\":\"refresh_token is invalid\"}",
"code": "invalid_request"
}
}
存储后,代理刷新访问权限token当它们过期时。如果提供商轮换刷新token并在刷新期间返回一个新的,新的token自动替换已存储的。
环境变量 #
安 environment_variable 凭证要求 value 和 injection_location:
credential = client.credentials.create(
id="slack-bot-token",
type="environment_variable",
value="xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx",
trusted_domains=["*.slack.com", "slack.com"],
injection_location="header",
)
const credential = await client.credentials.create({
id: "slack-bot-token",
type: "environment_variable",
value: "xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx",
trusted_domains: ["*.slack.com", "slack.com"],
injection_location: "header",
});
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/credentials"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
if err != nil {
log.Fatal(err)
}
res, err := client.Credentials.Create(ctx, operations.CreateCredentialRequest{
Body: credentials.NewCredentialCreateParams(credentials.EnvironmentVariableConfig{
ID: "slack-bot-token",
Value: "xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx",
TrustedDomains: []string{"*.slack.com", "slack.com"},
InjectionLocation: credentials.NewEnvironmentVariableConfigInjectionLocation(credentials.InjectionLocationEnumHeader),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Created environment variable credential: %s\n", res.Credential.ID)
}
curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"id": "slack-bot-token",
"type": "environment_variable",
"value": "xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx",
"trusted_domains": ["*.slack.com", "slack.com"],
"injection_location": "header"
}'
gemini-api credentials create --body '{
"id": "slack-bot-token",
"type": "environment_variable",
"value": "xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx",
"trusted_domains": ["*.slack.com", "slack.com"],
"injection_location": "header"
}'
该 injection_location 字段告诉代理在出站请求中的何处替换秘密。它接受 header, query, 或 body,当服务需要多个字符串时,可以作为单个字符串,也可以作为数组:
"injection_location": ["header", "query"]
替换仅发生在您列出的位置。在其他地方携带占位符的请求将被拒绝而不是继续发送。
要将凭证绑定到变量名称,请参阅 使用凭据作为环境变量.
生成的 ID #
该 id 字段是可选的。省略它,服务会生成一个 UUID:
{
"id": "9e545973-4330-49bb-9a44-930cea9fbe3c",
"type": "bearer_token",
"status": "active",
"create_time": "2026-07-15T10:00:00.000000000Z",
"update_time": "2026-07-15T10:00:00.000000000Z"
}
当您想要在交互中使用稳定、可读的参考时,请提供您自己的 ID。由于 ID 出现在资源路径中,因此最好使用带有连字符或下划线的小写字母数字。
列出凭据 #
列出属于您的项目的凭据。使用分页参数来控制响应批量大小。
response = client.credentials.list(page_size=10)
for credential in response.credentials:
print(f"Credential ID: {credential.id}, Type: {credential.type}")
const response = await client.credentials.list({ page_size: 10 });
for (const credential of response.credentials) {
console.log(`Credential ID: ${credential.id}, Type: ${credential.type}`);
}
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
if err != nil {
log.Fatal(err)
}
res, err := client.Credentials.List(ctx, operations.ListCredentialsRequest{
PageSize: genai.Ptr(10),
})
if err != nil {
log.Fatal(err)
}
for _, cred := range res.CredentialListResponse.Credentials {
fmt.Printf("Credential ID: %s, Type: %v\n", cred.ID, cred.GetType())
}
}
curl -X GET "https://generativelanguage.googleapis.com/v1beta/credentials?page_size=10" \
-H "x-goog-api-key: $GEMINI_API_KEY"
gemini-api credentials list --page-size 10
响应仅包含元数据:
{
"credentials": [
{
"id": "github-production",
"type": "bearer_token",
"status": "active",
"create_time": "2026-07-15T10:00:00.000000000Z",
"update_time": "2026-07-15T10:00:00.000000000Z"
},
{
"id": "jira-oauth",
"type": "oauth2",
"status": "active",
"create_time": "2026-07-15T10:05:00.000000000Z",
"update_time": "2026-07-15T10:05:00.000000000Z"
}
],
"next_page_token": "Cj...5aE="
}
通行证 next_page_token 返回为 page_token 获取下一页。当没有进一步结果时,该字段将被省略。
| 参数 | 类型 | 说明 |
|---|---|---|
page_size | 整数 | 每页的最大凭据数。 |
page_token | 字符串 | token来自 next_page_token 之前的回复。 |
获取凭证 #
通过 ID 检索特定凭证的元数据。
credential = client.credentials.get(id="github-production")
print(f"Credential ID: {credential.id}, Status: {credential.status}")
const credential = await client.credentials.get("github-production");
console.log(`Credential ID: ${credential.id}, Status: ${credential.status}`);
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
if err != nil {
log.Fatal(err)
}
res, err := client.Credentials.Get(ctx, operations.GetCredentialRequest{
ID: "github-production",
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Credential ID: %s, Status: %v\n", res.Credential.ID, res.Credential.GetStatus())
}
curl -X GET "https://generativelanguage.googleapis.com/v1beta/credentials/github-production" \
-H "x-goog-api-key: $GEMINI_API_KEY"
gemini-api credentials get github-production
响应类似于以下内容:
{
"id": "github-production",
"type": "bearer_token",
"status": "active",
"create_time": "2026-07-15T10:00:00.000000000Z",
"update_time": "2026-08-01T14:30:00.000000000Z"
}
请求不存在的凭证返回 404:
{
"error": {
"message": "Result not found.; GetCredential call failed",
"code": "not_found"
}
}
轮换凭证 #
替换机密而不触及引用它的任何许可名单规则、工具定义或环境变量。轮换在下一个代理解析时生效。
请求必须包括 type,加上您要更改的字段。您省略的字段保留其当前值。
旋转承载token:
credential = client.credentials.update(
id="github-production",
type="bearer_token",
token="ghp_new_xxxxxxxxxxxxxxxxxxxx",
)
const credential = await client.credentials.update("github-production", {
type: "bearer_token",
token: "ghp_new_xxxxxxxxxxxxxxxxxxxx",
});
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/credentials"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
if err != nil {
log.Fatal(err)
}
res, err := client.Credentials.Update(ctx, operations.UpdateCredentialRequest{
ID: "github-production",
Body: credentials.NewCredentialUpdate(credentials.HTTPBearerUpdateConfig{
Token: genai.Ptr("ghp_new_xxxxxxxxxxxxxxxxxxxx"),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Updated credential %s at %v\n", res.Credential.ID, res.Credential.GetUpdateTime())
}
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/credentials/github-production" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"type": "bearer_token",
"token": "ghp_new_xxxxxxxxxxxxxxxxxxxx"
}'
gemini-api credentials update github-production --body '{"type": "bearer_token", "token": "ghp_new_xxxxxxxxxxxxxxxxxxxx"}'
轮换 OAuth2 刷新 token:
credential = client.credentials.update(
id="jira-oauth",
type="oauth2",
refresh_token="rt_new_xxxxxxxxxxxxxxxxxxxx",
)
const credential = await client.credentials.update("jira-oauth", {
type: "oauth2",
refresh_token: "rt_new_xxxxxxxxxxxxxxxxxxxx",
});
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/credentials"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
if err != nil {
log.Fatal(err)
}
res, err := client.Credentials.Update(ctx, operations.UpdateCredentialRequest{
ID: "jira-oauth",
Body: credentials.NewCredentialUpdate(credentials.OAuth2UpdateConfig{
RefreshToken: genai.Ptr("rt_new_xxxxxxxxxxxxxxxxxxxx"),
}),
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Updated credential %s at %v\n", res.Credential.ID, res.Credential.GetUpdateTime())
}
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/credentials/jira-oauth" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"type": "oauth2",
"refresh_token": "rt_new_xxxxxxxxxxxxxxxxxxxx"
}'
gemini-api credentials update jira-oauth --body '{"type": "oauth2", "refresh_token": "rt_new_xxxxxxxxxxxxxxxxxxxx"}'
响应反映了新的 update_time:
{
"id": "jira-oauth",
"type": "oauth2",
"status": "active",
"create_time": "2026-07-15T10:05:00.000000000Z",
"update_time": "2026-08-01T14:30:00.000000000Z"
}
一个凭证的 type 被固定在创建时。要更改它,请删除凭据并创建一个新凭据。
删除凭证 #
当不再需要凭证及其存储的机密时,将其删除。
client.credentials.delete(id="github-production")
await client.credentials.delete("github-production");
package main
import (
"context"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}})
if err != nil {
log.Fatal(err)
}
_, err = client.Credentials.Delete(ctx, operations.DeleteCredentialRequest{
ID: "github-production",
})
if err != nil {
log.Fatal(err)
}
}
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/credentials/github-production" \
-H "x-goog-api-key: $GEMINI_API_KEY"
gemini-api credentials delete github-production
成功删除返回一个空对象:
{}
任何仍引用 ID 的白名单规则、工具或环境变量都将无法解析,因此请先更新它们。
现场参考 #
每个证书共有的字段:
| 领域 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | 字符串 | 否 | 唯一标识符。省略时生成为 UUID。 |
type | 字符串 | 是的 | 其中之一 bearer_token, oauth2, environment_variable. |
status | 字符串 | 只读 | 凭证的当前状态。 |
create_time | 字符串 | 只读 | RFC 3339 创建时间戳。 |
update_time | 字符串 | 只读 | RFC 3339 上次更新的时间戳。 |
字段用于 bearer_token:
| 领域 | 类型 | 必填 | 说明 |
|---|---|---|---|
token | 字符串 | 是的 | 只写。 token 值。 |
header_name | 字符串 | 否 | 要注入的标头。默认为 Authorization. |
prefix | 字符串 | 否 | 值前缀。默认为 Bearer。设置为 "" 没有一个。 |
字段用于 oauth2:
| 领域 | 类型 | 必填 | 说明 |
|---|---|---|---|
client_id | 字符串 | 是的 | OAuth2 客户端 ID。 |
client_secret | 字符串 | 是的 | 只写。 OAuth2 客户端密钥。 |
refresh_token | 字符串 | 是的 | 只写。刷新token用于获取token的访问权限。 |
token_url | 字符串 | 是的 | 提供者 token 端点。 |
scopes | 数组 | 否 | OAuth 请求范围。 |
字段用于 environment_variable:
| 领域 | 类型 | 必填 | 说明 |
|---|---|---|---|
value | 字符串 | 是的 | 只写。秘密值。 |
injection_location | 字符串或数组 | 是的 | 哪里可以替代秘密。一项或多项 header, query, body. |
trusted_domains | 数组 | 否 | 授权替换的域模式。 |
错误 #
错误返回一个 JSON 对象,其中包含 message 和一个 code:
{
"error": {
"message": "Credential 'github-production' already exists.; CreateCredential call failed",
"code": "aborted"
}
}
| HTTP状态 | code | 原因 |
|---|---|---|
| 400 | invalid_request | 缺少必填字段、未知字段、不受支持 type,或 OAuth2 验证失败。 |
| 404 | not_found | 没有该 ID 的凭证。 |
| 409 | aborted | 具有该 ID 的凭证已存在。 |
未知字段被拒绝而不是被忽略,并且错误命名该字段:
{
"error": {
"message": "Unknown parameter 'headerName'. Did you mean 'header_name'?",
"code": "invalid_request"
}
}