Bring Your Own Key (BYOK)

Bring Your Own Key (BYOK) runs the AI model calls behind CloudThinker on your own provider account. Your provider bills the tokens, and a turn on your key is charged only a reduced share of the CloudThinker credits the same turn costs on the platform’s models. Those credits show on the Usage page with the rest of your spend. Usage doesn’t split spend by whether your key was used.

BYOK doesn’t fail closed. If a call on your key fails, or the key is paused or inactive, the turn runs on CloudThinker’s platform models instead, and there’s no setting to turn that off. If your data may only reach your own provider account, watch for the BYOK Credentials Error alert and see When a key stops working.

Prerequisites

A Scale or Enterprise plan. On any other plan the BYOK page shows an Upgrade plan button. See Pricing.
An organization workspace. A personal workspace shows No key in a personal workspace.
The right role for the key you’re setting up:

Key	Who manages it	Where
Organization key, the default for every workspace	Organization Owner. Organization Admins see the key’s health, not its credentials, and can’t change it.	Admin Settings → BYOK
Workspace key, for one workspace only	Workspace Admin	More → Workspace settings → BYOK

Other members see whether a key is healthy, never its credentials.

Credentials from one provider:

Provider	What you need
AWS Bedrock	An IAM role CloudThinker can assume (recommended), or an IAM access key. Model access turned on in Amazon Bedrock for the models in Step 3, which shows each row’s default before you verify. For Anthropic models, AWS asks for a one-time use-case form first.
Anthropic	An Anthropic Console API key. It starts with `sk-ant`.
FPT Cloud	An FPT Cloud Marketplace API key.
Claude Code	A Claude account with a plan that covers Claude Code. You connect the account itself, with a Setup token, Browser sign-in, or by uploading `~/.claude/.credentials.json` from a Linux or Windows machine. On macOS, Claude Code keeps that file in the Keychain, so use a setup token instead.
Codex	A ChatGPT account with a plan that covers Codex. You connect the account itself, with a Device code, Browser sign-in, or by uploading `~/.codex/auth.json` from the Codex CLI. After an upload, sign out of Codex on that machine, or the two copies cancel each other out at the next token refresh.

Google Vertex and OpenAI-compatible providers show as Soon in the picker and can’t be selected yet.

Connect a key

Open BYOK settings

As the Owner, go to Admin Settings → BYOK. The page has two sections: This workspace (the workspace you’re in) and Organization key.As a workspace Admin, go to More → Workspace settings → BYOK, and set This workspace to Workspace.

Pick the provider

Under Step 1 Provider, select AWS Bedrock, Anthropic, FPT Cloud, Claude Code, or Codex.

Enter the credentials

Fill in Step 2 Credentials.Claude Code and Codex have no credential to paste. Their Step 2 is a connect step: give the credential an optional name, pick a method tab, and finish the sign-in. The credential connects on its own, so there’s no Step 3 and no Verify and activate button. Choose which rows run on it afterwards, in the What runs on which credential table under the key cards.

Bedrock: IAM role
Bedrock: access key
Anthropic
FPT Cloud

Set Sign in with to IAM role (the default). CloudThinker assumes the role for every call and stores no AWS key.

Trust CloudThinker. In AWS IAM, create a role with the trust policy the form shows. It has this shape, and the form fills in the real CloudThinker principal and an External ID unique to this key’s scope, so copy it from the form, not from another workspace:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "AWS": "<CloudThinker principal ARN from the form>" },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": { "sts:ExternalId": "<External ID from the form>" }
      }
    }
  ]
}

Allow Bedrock. Attach the permissions policy the form shows. The form shows the placeholder 111122223333 too, so replace it with your AWS account ID yourself:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CloudThinkerInvokeModels",
      "Effect": "Allow",
      "Action": ["bedrock:InvokeModel*"],
      "Resource": [
        "arn:aws:bedrock:*:111122223333:inference-profile/*",
        "arn:aws:bedrock:*::foundation-model/*",
        "arn:aws:bedrock:::foundation-model/*"
      ]
    },
    {
      "Sid": "CloudThinkerInvokeMantle",
      "Effect": "Allow",
      "Action": ["bedrock-mantle:CreateInference"],
      "Resource": "arn:aws:bedrock-mantle:*:111122223333:project/*"
    }
  ]
}

The two foundation-model resources cover both ARN forms Bedrock uses for a base model, with and without a region. The bedrock-mantle statement covers Bedrock’s Mantle inference API, which serves OpenAI models on Bedrock. Keep it if you want those models available on your key.

Role ARN. Paste the new role’s ARN.
Region. Keep Global (recommended) or pick one AWS region. See Choose a Bedrock region.

Set Sign in with to Access key. Create an IAM user, attach the same permissions policy shown on the IAM role tab, and create an access key for it.

Access key ID: AKIA... for a permanent key, ASIA... for a temporary one.
Secret access key: the secret for that key.
Session token: only for a temporary ASIA key.
Region: keep Global (recommended) or pick one AWS region.

Prefer an IAM role. If you must use a key, use a permanent AKIA key: CloudThinker trades it for short-lived session tokens and renews them. A temporary ASIA key can’t be renewed and stops working when it expires.

API key: your Anthropic Console key, sk-ant-....
Base URL: leave empty unless your key runs through a gateway. Empty means https://api.anthropic.com.

API key: your FPT Cloud Marketplace API key.
Base URL: leave empty unless your key runs through a gateway. Empty means https://mkp-api.fptcloud.com/v1.

Choose the models

Step 3 Models on your key lists each kind of work with the model your key runs for it. Keep the defaults, or click Customize models to change a row or set it to CloudThinker credits. At least one row must run on your key, or the button stays disabled with Pick a model for at least one row.

Verify and activate

Click Verify and activate. CloudThinker sends one short request per model you picked (one output token, billed by your provider), then saves and turns on the key.Success state: a key card shows Active, the key hint, the region (Bedrock), and a verified time. In chat, a Your key badge appears next to the message input. To confirm on your side, look for InvokeModel calls by the role in AWS CloudTrail, or check usage in the Anthropic Console.

CloudThinker encrypts credentials at rest and never sends a saved secret back to the browser.

What runs on your key

Each row in Step 3 is one kind of work. A row you set to CloudThinker credits runs on the platform and is billed as usual.

Row	Covers
Light, Pro, Ultra	Chat turns in that mode
Review	Review of pull and merge requests
Cyber	Cyber test runs, Cyber chat, and Code Audit
Resolve	Resolve root cause analysis
Optimize	Optimize. Defaults to the Ultra row’s model.
Background tasks	Supporting work that runs behind a turn. Defaults to the Light row’s model.

The other rows’ defaults are set per provider by the current CloudThinker release, so they change as models ship. Step 3 shows each one before you verify, which is the list to turn on in Bedrock model access. The model list comes from your provider. The picker only offers models your provider serves on this key and region. If a saved pick shows Model retired, pick another, choose a new model for that row.

Choose a Bedrock region

Region decides where Bedrock may serve your requests. You pick a region; CloudThinker picks the matching Bedrock cross-region inference profile (us., eu., apac., or global.).

You pick	Profile	Bedrock serves requests from
Global (recommended)	`global.`	Any commercial AWS region. Widest model choice.
A US or Canada region, such as `us-east-1`	`us.`	US regions
An EU, Middle East, or Israel region, such as `eu-west-1`	`eu.`	EU regions
An Asia Pacific region, such as `ap-southeast-1`	`apac.`	Asia Pacific regions
Any other region, such as South America (Sao Paulo)	`global.`	Any commercial AWS region, same as Global

A South America pick runs as Global, so requests can leave South America. A regional pick narrows the model list to what Bedrock serves in that geography. If your data must stay in one geography, keep a regional pick and check after setup that every row still runs on your key.

Organization and workspace keys

This workspace decides which key the workspace runs on:

Choice	Result
Organization	Turns run on the organization key. If it isn’t active, they spend CloudThinker credits.
Workspace	Turns run on a key set up for this workspace only.
Off	Turns spend CloudThinker credits, even when the organization has a key.

The line under the choice tells you what’s in effect, for example “Turns run on the organization’s AWS Bedrock key.” To force every workspace onto the organization key, the Owner turns on Require the organization key in every workspace under Organization key. Workspace Admins then can’t add their own key or turn BYOK off.

Manage a key

Action	What it does
Rotate key	Replace the credentials. CloudThinker verifies the new ones with Verify and save and keeps your model picks.
Edit models	Choose which of the provider’s models are allowed on this key. Leave at least one on.
Re-verify	Test the saved credentials again.
Pause / Activate	Stop or restart calls on the key. A paused key keeps its credentials and shows Saved, paused.
Remove	Delete the key. Every row goes back to CloudThinker credits.

Two different settings decide which model runs:

Setting	What it decides	Where to change it
Allowed models	Which of the provider’s models this key may use at all	Edit models on the key card
Row assignments	Which allowed model each row (Light, Review, and so on) uses	The What runs on which credential table under the key cards, then Save. During setup, the same choice is Customize models in Step 3.

When a key stops working

If a call on your key fails, CloudThinker falls back to a platform model so the work finishes. That call spends CloudThinker credits. That includes a call your provider throttles, so if Bedrock quotas are low for your workload, raise them in AWS Service Quotas to keep turns on your key. If the provider rejects the credentials (expired token, revoked key, access denied), CloudThinker turns the key off:

The key card shows Disabled after error or Key expired, with the provider’s error code.
A high-severity notification titled BYOK Credentials Error goes to the workspace where the call failed, naming the provider and the error code.
Turns keep running on CloudThinker credits until you fix the key.

To restore it, click Rotate key, enter working credentials, and click Verify and save.

Troubleshooting

Verification failed

The red Verification failed box shows the provider’s own error text.

Bedrock access denied: check the role or user has the Allow Bedrock policy, and that the trust policy uses the External ID from this form.
Model not available: turn on model access for that model in the Bedrock console, or pick another model for the row.
One row can’t be served: set that row to CloudThinker credits and verify again.

Access denied only after picking a region

Bedrock doesn’t serve every model in every geography. Switch Region to Global (recommended), or pick a model that geography serves.

The key keeps turning itself off

A temporary ASIA access key expires and can’t be renewed. Rotate to an IAM role or a permanent AKIA key.

No Your key badge in chat

The key card must show Active, not Saved, paused.
The workspace’s This workspace choice must not be Off.
With Organization chosen, the organization key itself must be active.

I can't change the workspace setting

Either you aren’t a workspace Admin, or the Owner turned on Require the organization key in every workspace. The page says which.

Next steps

Usage

See the credits your workspaces spend

Credit limits

Cap what each workspace can spend on platform credits

Notifications

Make sure the right people get the BYOK credentials alert

Data protection

What the model sees, and which secrets and identifiers are masked first

Security and trust

Identity and access

Governance

Deployment

Bring Your Own Key (BYOK)

Prerequisites

Connect a key

What runs on your key

Choose a Bedrock region

Organization and workspace keys

Manage a key

When a key stops working

Troubleshooting

Next steps

Usage

Credit limits

Notifications

Data protection

​Prerequisites

​Connect a key

​What runs on your key

​Choose a Bedrock region

​Organization and workspace keys

​Manage a key

​When a key stops working

​Troubleshooting

​Next steps

Usage

Credit limits

Notifications

Data protection

Prerequisites

Connect a key

What runs on your key

Choose a Bedrock region

Organization and workspace keys

Manage a key

When a key stops working

Troubleshooting

Next steps