***

title: AI Credentials
description: >-
Manage AI provider credentials that workspaces and agents use for LLM-powered
automation.
-----------

AI credentials give your workspaces access to LLM providers — OpenAI, Anthropic, Google, or any OpenAI-compatible endpoint. Agents like Stagehand and browser-use use these credentials to reason about pages and execute instructions.

Access via `bctrl.aiCredentials`.

## list()

List all AI credentials in your organization.

```ts
const credentials = await bctrl.aiCredentials.list();
```

**Returns** `AiCredential[]`

***

## create(request)

Create a new AI credential.

```ts
await bctrl.aiCredentials.create({
  id: "openai-prod",
  provider: "openai",
  label: "Production OpenAI",
  apiKey: "sk-...",
  defaultModel: "gpt-4o",
});
```

| Parameter      | Type                                                         | Required | Description                                      |
| -------------- | ------------------------------------------------------------ | -------- | ------------------------------------------------ |
| `id`           | `string`                                                     | Yes      | Unique identifier for this credential            |
| `provider`     | `'openai' \| 'anthropic' \| 'google' \| 'openai-compatible'` | Yes      | AI provider                                      |
| `label`        | `string`                                                     | Yes      | Human-readable label                             |
| `apiKey`       | `string`                                                     | Yes      | Provider API key                                 |
| `baseUrl`      | `string`                                                     | No       | Custom base URL (for openai-compatible)          |
| `defaultModel` | `string`                                                     | No       | Default model to use                             |
| `enabled`      | `boolean`                                                    | No       | Whether the credential is active (default: true) |

**Returns** `AiCredential`

***

## get(id)

Get a specific credential by ID.

```ts
const cred = await bctrl.aiCredentials.get("openai-prod");
```

| Parameter | Type     | Required | Description   |
| --------- | -------- | -------- | ------------- |
| `id`      | `string` | Yes      | Credential ID |

**Returns** `AiCredential`

***

## update(id, request)

Update an existing credential.

```ts
await bctrl.aiCredentials.update("openai-prod", {
  defaultModel: "gpt-4o-mini",
  enabled: true,
});
```

| Parameter | Type                        | Required | Description      |
| --------- | --------------------------- | -------- | ---------------- |
| `id`      | `string`                    | Yes      | Credential ID    |
| `request` | `AiCredentialUpdateRequest` | Yes      | Fields to update |

**Returns** `AiCredential`

***

## delete(id)

Delete a credential.

```ts
await bctrl.aiCredentials.delete("openai-prod");
```

| Parameter | Type     | Required | Description   |
| --------- | -------- | -------- | ------------- |
| `id`      | `string` | Yes      | Credential ID |

***

## test(id)

Test that a credential can connect to its provider.

```ts
const result = await bctrl.aiCredentials.test("openai-prod");
```

| Parameter | Type     | Required | Description   |
| --------- | -------- | -------- | ------------- |
| `id`      | `string` | Yes      | Credential ID |

**Returns** `AiCredentialTestResponse`

***

## Usage with workspaces

Credentials are mounted to workspaces via the `ai` mount. See [Scopes & Inheritance](/sdk/concepts/scopes-and-inheritance) for details.

```ts
const workspace = await bctrl.workspaces.create({
  name: "my-agent",
  mounts: {
    ai: {
      allow: ["openai-prod"],
      defaults: { openai: "openai-prod" },
    },
  },
});
```