# Credentials

> Store provider keys, database connections, and tool secrets once, then reuse them safely across the workspace.

Source: https://0.0.0.0:3000/credentials

Credentials store the API keys, connection strings, OAuth tokens, and secrets PromptRails needs to call models, databases, media providers, and external tools. They belong to a workspace, are encrypted at rest, and are never returned in API responses.

If you use PromptRails-hosted models through the [LLM Gateway](/docs/llm-gateway), you do not need to add a provider credential for those models. Credentials are still used for bring-your-own-key providers, databases, media tools, and external services.

## When You Need a Credential

Add a credential when PromptRails needs to call something owned by your team:

- A model provider account your company controls
- A database or warehouse used by a data source
- A tool secret, OAuth token, SMTP server, or external API key
- A media provider used by an agent tool

After a credential is created, agents, prompts, data sources, tools, and media workflows can reference it without exposing the raw secret to users or API responses.

## Choosing the Right Type

Start from the product question, not the provider list:

- **Need model access with your own vendor account?** Add an LLM provider credential.
- **Need agents to query company data?** Add a data warehouse credential, then attach it to a data source in Studio.
- **Need a specific tool secret?** Configure it from the tool in Studio, because tool credentials belong to that tool setup.
- **Need hosted models without managing provider keys?** Use the [LLM Gateway](/docs/llm-gateway) instead of adding a provider key.

## Credential Categories

Credentials are organized by what they connect to:

### LLM Credentials

Connect to LLM providers for prompt execution and agent orchestration.

| Provider      | Type Identifier | Description                       |
| ------------- | --------------- | --------------------------------- |
| OpenAI        | `openai`        | GPT-4, GPT-4o, GPT-3.5, etc.      |
| Anthropic     | `anthropic`     | Claude 3.5, Claude 3, etc.        |
| Google Gemini | `gemini`        | Gemini Pro, Gemini Ultra, etc.    |
| DeepSeek      | `deepseek`      | DeepSeek chat and code models     |
| Fireworks     | `fireworks`     | Fireworks AI hosted models        |
| xAI           | `xai`           | Grok models                       |
| OpenRouter    | `openrouter`    | Multi-provider routing            |
| Together AI   | `together_ai`   | Together AI hosted models         |
| Mistral       | `mistral`       | Mistral AI models                 |
| Cohere        | `cohere`        | Cohere command and embed models   |
| Groq          | `groq`          | Groq high-speed inference         |
| Perplexity    | `perplexity`    | Search-augmented Sonar models     |
| AWS Bedrock   | `bedrock`       | Claude, Llama, Nova & more on AWS |
| Cerebras      | `cerebras`      | Cerebras high-speed inference     |
| SambaNova     | `sambanova`     | SambaNova hosted models           |
| Hyperbolic    | `hyperbolic`    | Hyperbolic hosted models          |
| DeepInfra     | `deepinfra`     | DeepInfra hosted models           |
| Novita AI     | `novita`        | Novita AI hosted models           |
| Friendli AI   | `friendli`      | Friendli AI hosted models         |
| Chutes AI     | `chutes`        | Chutes AI hosted models           |
| Z.AI          | `zai`           | Z.AI (GLM) models                 |
| Moonshot      | `moonshot`      | Moonshot (Kimi) models            |
| DashScope     | `dashscope`     | Alibaba DashScope (Qwen) models   |
| Hugging Face  | `huggingface`   | Hugging Face Router models        |

<Callout type="info">
  **AWS Bedrock** uses AWS Signature V4 rather than a single API key. When you add a `bedrock`
  credential, supply an **Access Key ID**, **Secret Access Key** and **Region** (plus an optional
  **Session Token** for temporary/STS credentials) instead of one key string.
</Callout>

Not every provider supports every feature — see [Prompts](/docs/prompts#model-capabilities) for how reasoning, web search, prompt caching, and structured output appear in prompt settings.

### Speech Credentials

Connect to speech providers for text-to-speech and speech-to-text.

| Provider     | Type Identifier | Description                        |
| ------------ | --------------- | ---------------------------------- |
| ElevenLabs   | `elevenlabs`    | High-quality TTS voices            |
| Deepgram     | `deepgram`      | TTS and STT with Nova models       |
| OpenAI Audio | `openai_audio`  | OpenAI TTS (tts-1) and Whisper STT |

### Image Credentials

Connect to image generation and editing providers.

| Provider     | Type Identifier | Description                      |
| ------------ | --------------- | -------------------------------- |
| Fal          | `fal`           | Fast image generation (FLUX, SD) |
| Replicate    | `replicate`     | Run open-source models           |
| Stability AI | `stability`     | Stable Diffusion models          |
| OpenAI Image | `openai_image`  | DALL-E 3 and DALL-E 2            |

### Video Credentials

Connect to video generation providers.

| Provider | Type Identifier | Description                    |
| -------- | --------------- | ------------------------------ |
| Runway   | `runway`        | Gen-3 Alpha video generation   |
| Pika     | `pika`          | AI video generation            |
| Luma     | `luma`          | Dream Machine video generation |

### Data Warehouse Credentials

Connect to databases for data source queries.

| Database    | Type Identifier | Description                     |
| ----------- | --------------- | ------------------------------- |
| PostgreSQL  | `postgresql`    | PostgreSQL connection string    |
| MySQL       | `mysql`         | MySQL connection string         |
| BigQuery    | `bigquery`      | Google BigQuery service account |
| Snowflake   | `snowflake`     | Snowflake account credentials   |
| Redshift    | `redshift`      | Amazon Redshift connection      |
| MSSQL       | `mssql`         | Microsoft SQL Server            |
| ClickHouse  | `clickhouse`    | ClickHouse connection           |
| Static File | `static_file`   | File-based data access          |

### Tool Credentials

Credentials for external APIs and services used by MCP tools.

| Type       | Description                                             |
| ---------- | ------------------------------------------------------- |
| `api_key`  | Generic API key authentication                          |
| `oauth`    | OAuth token-based authentication                        |
| `database` | Generic database connection (with schema_type required) |
| `smtp`     | SMTP server credentials                                 |

## Creating Credentials

Create credentials from workspace settings for normal setup. Use SDK calls when an internal platform needs to provision or rotate credentials programmatically.

<TechnicalDetails title="Create and manage credentials with SDKs">

**Python SDK**

```python
# LLM credential
credential = client.credentials.create(
    name="OpenAI Production",
    category="llm",
    type="openai",
    value="sk-proj-your-openai-api-key",
    description="Production OpenAI API key"
)

# Data warehouse credential
db_credential = client.credentials.create(
    name="Analytics Database",
    category="data_warehouse",
    type="postgresql",
    value="postgresql://user:password@host:5432/analytics",
    description="Read-only analytics database"
)

# Speech credential
speech_credential = client.credentials.create(
    name="ElevenLabs Production",
    category="speech",
    type="elevenlabs",
    value="your-elevenlabs-api-key",
    description="ElevenLabs TTS API key"
)

# Tool credential
tool_credential = client.credentials.create(
    name="Slack Bot Token",
    category="tools",
    type="api_key",
    value="xoxb-your-slack-bot-token",
    description="Slack bot for notifications"
)
```

**JavaScript SDK**

```typescript
const credential = await client.credentials.create({
  name: 'OpenAI Production',
  category: 'llm',
  type: 'openai',
  value: 'sk-proj-your-openai-api-key',
  description: 'Production OpenAI API key',
})
```

## Default Credentials

You can mark one credential per type as the default. Default credentials are automatically used when no specific credential is specified:

```python
client.credentials.set_default(credential_id="your-credential-id")
```

When an agent or prompt references a model from a provider (e.g., OpenAI), PromptRails uses the default credential for that provider type unless overridden.

## Connection Validation

Validate that a credential can successfully connect to its target service:

```python
result = client.credentials.validate(credential_id="your-credential-id")
print(f"Valid: {result['data']['is_valid']}")
```

Validation checks vary by credential type:

- LLM credentials: Makes a lightweight API call to verify the key
- Database credentials: Attempts a connection and basic query
- Tool credentials: Depends on the tool configuration

## Schema Discovery

For data warehouse credentials, PromptRails can discover the database schema (tables, columns, types):

```python
# Trigger schema discovery
client.credentials.discover_schema(credential_id="your-credential-id")

# Get the discovered schema
credential = client.credentials.get(credential_id="your-credential-id")
if credential["data"]["has_schema"]:
    print(f"Schema updated: {credential['data']['schema_updated_at']}")
```

The discovered schema includes:

- Table names
- Column names and data types
- Nullability
- Default values
- Descriptions (where available)

This schema information helps agents understand the database structure when constructing queries.

</TechnicalDetails>

<TechnicalDetails title="Credential API details">

## Credential Response

API responses include a safe representation of credentials (never the raw value):

| Field               | Description                                                     |
| ------------------- | --------------------------------------------------------------- |
| `id`                | Unique credential identifier                                    |
| `name`              | Display name                                                    |
| `type`              | Provider or database type                                       |
| `category`          | `llm`, `speech`, `image`, `video`, `data_warehouse`, or `tools` |
| `description`       | Optional description                                            |
| `masked_content`    | Masked credential value (e.g., `sk-pr...abcd`)                  |
| `is_default`        | Whether this is the default for its type                        |
| `is_valid`          | Whether the last validation check passed                        |
| `has_schema`        | Whether schema information is available                         |
| `schema_updated_at` | When the schema was last discovered                             |
| `created_at`        | Creation timestamp                                              |
| `updated_at`        | Last update timestamp                                           |

## Updating Credentials

When you update a credential, the new value is encrypted and stored. The previous value cannot be recovered.

```python
client.credentials.update(
    credential_id="your-credential-id",
    value="new-api-key-value",
    name="Updated Name"
)
```

## Deleting Credentials

Credentials are soft-deleted. Deleting a credential does not affect historical execution traces but will prevent future use.

```python
client.credentials.delete(credential_id="your-credential-id")
```

</TechnicalDetails>

## Related Topics

- [Assets and Media](/docs/assets) -- Using credentials for speech, image, and video tools
- [Data Sources](/docs/data-sources) -- Using credentials for database queries
- [LLM Gateway](/docs/llm-gateway) -- Calling hosted models without adding a provider key
- [MCP Tools](/docs/mcp-tools) -- Using credentials for tool authentication
- [Security](/docs/security) -- Encryption and security practices