BYOK

Overview

Base path: https://api.infrai.cc/v1/byok

Auth header: Authorization: Bearer $INFRAI_API_KEY

bash

# Call any /v1/byok capability over raw HTTP — no SDK to install.
# curl:
curl https://api.infrai.cc/v1/byok/... \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json"

Methods

byok.register

POST /v1/byok/register

Parameters

Name	Type	Required	Description
`provider`	`ByokProvider \| string`	Required	Vendor provider id, e.g. openai.
`alias`	`string`	Required	A label you choose for this credential.
`credentials`	`Record<string, string>`	Required	Vendor credential fields (write-only).
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

ByokKey { byok_id, provider, alias, state, created_at, test_result? }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/register \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "module": "ai-runtime", "api_key": "sk-..."}'

byok.list

GET /v1/byok/list

List your registered BYOK credentials.

Returns

{ items: ByokKey[] }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/byok/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

byok.test

POST /v1/byok/test/{id}

Test a BYOK credential's connectivity.

Parameters

Name	Type	Required	Description
`id`	`string`	Required	The BYOK credential id.

Returns

{ ok, latency_ms?, error? }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/test/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

byok.revoke

DELETE /v1/byok/revoke/{id}

Revoke a BYOK credential.

Parameters

Name	Type	Required	Description
`id`	`string`	Required	The BYOK credential id.

Returns

{ ok: boolean }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X DELETE https://api.infrai.cc/v1/byok/revoke/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

byok.get

GET /v1/byok/get/{id}

获取单个 BYOK 凭证的配置详情，包括 provider、状态与绑定列表。

Parameters

Name	Type	Required	Description
`id`	`string`	Required	BYOK 凭证 ID。

Returns

ByokConfig { byok_id, provider, label?, state, bindings[], created_at }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/byok/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

byok.update

PATCH /v1/byok/update/{id}

更新 BYOK 凭证的元数据（如 label），不重新注册、不改动密钥。模块绑定请用 bind 管理。

Parameters

Name	Type	Required	Description
`id`	`string`	Required	BYOK 凭证 ID。
`label`	`string`	Optional	该凭证的新可读名称。
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

ByokConfig { byok_id, provider, label?, state, bindings[] }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X PATCH https://api.infrai.cc/v1/byok/update/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

byok.enable

POST /v1/byok/enable/{id}

启用此 BYOK 凭证，使其重新参与路由。

Parameters

Name	Type	Required	Description
`id`	`string`	Required	BYOK 凭证 ID。
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

ByokConfig { byok_id, state, bindings[] }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/enable/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

byok.disable

POST /v1/byok/disable/{id}

停用此 BYOK 凭证，停止经其路由但不删除。

Parameters

Name	Type	Required	Description
`id`	`string`	Required	BYOK 凭证 ID。
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

ByokConfig { byok_id, state, bindings[] }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/disable/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

byok.bind

POST /v1/byok/bind/{id}

将凭证绑定到某个 capability 或 module（可选锁定到具体 model），路由按最具体优先匹配；capability/module 至少传一个。

Parameters

Name	Type	Required	Description
`id`	`string`	Required	BYOK 凭证 ID。
`capability`	`string`	Optional	要绑定的能力，例如 'ai.chat'。
`module`	`string`	Optional	要绑定的模块，例如 'ai-runtime'。
`model`	`string`	Optional	可选，在绑定范围内锁定的模型。
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

ByokConfig { byok_id, bindings[] }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/bind/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

byok.unbind

POST /v1/byok/unbind/{id}

移除一个绑定；capability/module 至少传一个。返回含 bindings 的 BYOK 配置。

Parameters

Name	Type	Required	Description
`id`	`string`	Required	BYOK 凭证 ID。
`capability`	`string`	Optional	要解绑的能力，例如 'ai.chat'。
`module`	`string`	Optional	要解绑的模块，例如 'ai-runtime'。
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

ByokConfig { byok_id, bindings[] }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/unbind/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

byok.policy.get

GET /v1/byok/policy/get

读取当前账户的 BYOK 路由策略（byok_only / byok_then_pool 及可选 scope）。

Returns

ByokPolicy { mode, scope? }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/byok/policy/get \
  -H "Authorization: Bearer $INFRAI_API_KEY"

byok.policy.set

POST /v1/byok/policy/set

设置 BYOK 路由策略：byok_only 永不回退共享池，byok_then_pool 在 BYOK 失败时回退；scope 可缩小到某能力或模块。

Parameters

Name	Type	Required	Description
`mode`	`'byok_only' \| 'byok_then_pool'`	Required	byok_only=永不回退共享池；byok_then_pool=BYOK 失败时回退。
`scope`	`{ capability?: string; module?: string }`	Optional	可选缩小范围；省略时为账户级。
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

ByokPolicy { mode, scope? }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/policy/set \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "byok_only"}'

byok.quota.set

POST /v1/byok/quota/set/{id}

为单个 BYOK 凭证设置花费/调用上限，防止失控用量。

Parameters

Name	Type	Required	Description
`id`	`string`	Required	BYOK 凭证 ID。
`spend_limit_usd`	`number`	Optional	花费上限（美元），最小为 0。
`call_limit`	`number`	Optional	调用次数上限，最小为 0。
`window`	`'1d' \| '7d' \| '30d' \| 'mtd' \| 'ytd'`	Optional	配额重置窗口，与 UsageInfo.period 词表一致（1d/7d/30d/mtd/ytd）。
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

ByokConfig { byok_id, quota? }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/quota/set/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

byok.usage

GET /v1/byok/usage/{id}

查询单个 BYOK 凭证的用量（花费、调用次数、周期）。

Parameters

Name	Type	Required	Description
`id`	`string`	Required	BYOK 凭证 ID。

Returns

ByokUsage { byok_id, spend_usd, call_count, period }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/byok/usage/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

byok.events

GET /v1/byok/events/{id}

分页读取某个 BYOK 凭证的事件流（注册、轮换、绑定变更等）。

Parameters

Name	Type	Required	Description
`id`	`string`	Required	BYOK 凭证 ID。
`cursor`	`string`	Optional	分页游标，用于获取下一页。
`limit`	`number`	Optional	单页返回的最大条数。

Returns

{ items: ByokEvent[], next_cursor? }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X GET https://api.infrai.cc/v1/byok/events/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

byok.rotate

POST /v1/byok/rotate/{id}

原地替换密钥，保留 byok_id 与全部绑定，并触发 byok.rotated webhook。

Parameters

Name	Type	Required	Description
`id`	`string`	Required	BYOK 凭证 ID。
`api_key`	`string`	Required	新的明文厂商密钥；落库时信封加密，永不返回。
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

ByokConfig { byok_id, state, bindings[] }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/rotate/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "..."}'

byok.rotate.stage

POST /v1/byok/rotate/stage/{id}

暂存一个候选密钥并探测其可用性，但不切换流量；之后用 rotate.commit 提交。

Parameters

Name	Type	Required	Description
`id`	`string`	Required	BYOK 凭证 ID。
`api_key`	`string`	Required	候选明文厂商密钥；落库时信封加密，永不返回。
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

{ stage_id, probe_result? }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/rotate/stage/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "..."}'

byok.rotate.commit

POST /v1/byok/rotate/commit/{id}

将暂存的候选密钥提升为生效并切换流量，返回 BYOK 配置。

Parameters

Name	Type	Required	Description
`id`	`string`	Required	BYOK 凭证 ID。
`stage_id`	`string`	Required	byok.rotate.stage 返回的暂存句柄。
`idempotency_key`	`string`	Optional	Optional dedup key; identical retries return the same result.

Returns

ByokConfig { byok_id, state, bindings[] }

Example

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

curl -X POST https://api.infrai.cc/v1/byok/rotate/commit/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stage_id": "..."}'

All capabilities

Every routed capability in this module — the complete public REST contract. The methods above are the guided walkthrough; this index is the full reference.

Capability	Endpoint	Description
`byok.bind`	`POST /v1/byok/bind/{id}`	Bind a BYOK credential to a capability or module (optionally pinning a model); most-specific match wins.
`byok.disable`	`POST /v1/byok/disable/{id}`	Disable a BYOK credential, halting routing through it without deleting it.
`byok.enable`	`POST /v1/byok/enable/{id}`	Re-enable a BYOK credential so it rejoins routing.
`byok.events`	`GET /v1/byok/events/{id}`	Page through the event stream for a single BYOK credential.
`byok.get`	`GET /v1/byok/get/{id}`	Retrieve configuration for one BYOK credential (provider, status, bindings).
`byok.list`	`GET /v1/byok/list`	List the bring-your-own-vendor (BYOK) credentials registered on this account.
`byok.policy.get`	`GET /v1/byok/policy/get`	Read the account's BYOK routing policy.
`byok.policy.set`	`POST /v1/byok/policy/set`	Set the BYOK routing policy (byok_only or byok_then_pool, optionally scoped).
`byok.quota.set`	`POST /v1/byok/quota/set/{id}`	Set a spend or call-count limit on a single BYOK credential.
`byok.register`	`POST /v1/byok/register`	Register a bring-your-own vendor credential (provider, api_key) on the account; idempotent.
`byok.revoke`	`DELETE /v1/byok/revoke/{id}`	Revoke a BYOK credential; idempotent.
`byok.rotate`	`POST /v1/byok/rotate/{id}`	Replace a BYOK secret in place, preserving the credential ID and all bindings.
`byok.rotate.commit`	`POST /v1/byok/rotate/commit/{id}`	Promote the staged candidate secret to active and switch traffic over to it.
`byok.rotate.stage`	`POST /v1/byok/rotate/stage/{id}`	Stage and probe a candidate secret without switching traffic to it.
`byok.test`	`POST /v1/byok/test/{id}`	Test whether a BYOK credential is working; idempotent.
`byok.unbind`	`POST /v1/byok/unbind/{id}`	Remove a capability or module binding from a BYOK credential.
`byok.update`	`PATCH /v1/byok/update/{id}`	Update BYOK credential metadata (e.g. label) without changing the secret or re-registering.
`byok.usage`	`GET /v1/byok/usage/{id}`	Query usage (spend, call count, period) for a single BYOK credential.

End-to-end example

A production-style walkthrough of this module: configure once, then run the flow. It exercises most of the module's APIs.

一次性前置(每个范例都假定已完成):

bash

# No SDK to install — every call is a plain HTTPS request.
# Get a project key by signing in at the console: Google/GitHub gives you
# $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
# POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."

bash

# 1) Auth: every call is a raw HTTPS request to the Infrai gateway carrying
#    only your project key. No SDK, no install.
#    Get your key: sign in with Google/GitHub at the console for a project key
#    + $2 free credit (email sign-in starts at $0). On 402 INSUFFICIENT_CREDIT,
#    POST /v1/account/topup and open the returned checkout_url.
export INFRAI_API_KEY="ifr_pk_proj_..."   # from the console


# 2) byok.register
curl -X POST https://api.infrai.cc/v1/byok/register \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "module": "ai-runtime", "api_key": "sk-..."}'

# 3) byok.list
curl -X GET https://api.infrai.cc/v1/byok/list \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 4) byok.test
curl -X POST https://api.infrai.cc/v1/byok/test/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# 5) byok.revoke
curl -X DELETE https://api.infrai.cc/v1/byok/revoke/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 6) byok.get
curl -X GET https://api.infrai.cc/v1/byok/get/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY"

# 7) byok.update
curl -X PATCH https://api.infrai.cc/v1/byok/update/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# 8) byok.enable
curl -X POST https://api.infrai.cc/v1/byok/enable/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# 9) byok.disable
curl -X POST https://api.infrai.cc/v1/byok/disable/ID \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'