API Keys & Secrets

Overview

Tesslate Studio provides encrypted storage for API keys, environment variables, and other sensitive data your projects need. Keys are encrypted at rest using Fernet symmetric encryption, decrypted only when needed for API calls, and never exposed in logs or exports.

Encrypted Storage

All keys encrypted with Fernet symmetric encryption at rest

Per-Project Scoping

Set different keys for different projects, with user-level defaults as fallback

BYOK Support

Bring Your Own Key for AI models on Pro and Ultra tiers

CSRF Protection

State-changing requests are protected by CSRF tokens

Types of Secrets

AI Provider Keys
Deployment Credentials
Git Provider Tokens
Project Environment Variables

For AI model access (BYOK)Supported providers:

OpenAI: GPT-4, GPT-3.5 Turbo (provider key: openai)
Anthropic: Claude 3 Opus, Sonnet, Haiku (provider key: anthropic)
OpenRouter: 100+ models via unified API (provider key: openrouter)
Google: Gemini Pro (provider key: google)

When you add your own API key, requests for that provider route through your key instead of platform credits. This is called BYOK (Bring Your Own Key), available on Pro and Ultra tiers.

For external hosting platforms

Vercel OAuth tokens
Netlify OAuth tokens
Cloudflare API tokens with account ID
Supabase service role keys

These are stored in the DeploymentCredential model with encrypted access_token_encrypted and a provider_metadata JSON field for account IDs and team IDs.

For version control integration

GitHub OAuth (scopes: repo, user:email, read:user)
GitLab OAuth (scopes: api, read_user)
Bitbucket OAuth (scopes: repository, account)

Stored in the GitProviderCredential model with automatic token refresh support.

Managing AI Provider Keys

Adding Your Keys

Open Settings

Click your profile icon, then Settings. Navigate to the API Keys section.

Select Provider

Choose from: OpenAI, Anthropic, OpenRouter, Google, or GitHub.

Enter Your Key

Paste your API key from the provider’s dashboard. You can optionally give it a friendly name (e.g., “Production Key”).

Save

Click Save. The key is encrypted using Fernet encryption and stored in the UserAPIKey table. The raw key is never stored in plaintext.

Verify

Test by using an AI agent. If you have a valid key for the model’s provider, requests will use your key (BYOK) and cost zero platform credits.

How BYOK Detection Works

When you send a message to an AI agent, the credit system checks if the selected model uses a BYOK provider:

The is_byok_model(model_name) function checks against the BUILTIN_PROVIDERS list
If the model provider matches one of your stored API keys, it is treated as BYOK
BYOK requests cost $0 in platform credits (a UsageLog entry is still created with is_byok=True for analytics)
Adding a new provider to BUILTIN_PROVIDERS automatically makes it recognized as BYOK

BYOK is available on Pro and Ultra subscription tiers. Free and Basic tiers use platform credits for all AI requests.

Getting API Keys

OpenAI

Go to platform.openai.com
Sign up or log in
Navigate to API Keys
Click Create new secret key
Copy the key immediately (it is shown only once)

Models available: GPT-4, GPT-4 Turbo, GPT-3.5 Turbo

Anthropic (Claude)

Go to console.anthropic.com
Sign up or log in
Navigate to API Keys
Click Create Key
Copy the key immediately

Models available: Claude 3 Opus, Claude 3 Sonnet, Claude 3 Haiku

OpenRouter

Go to openrouter.ai
Sign up and go to Keys
Generate an API key
Copy the key

Models available: 100+ models including OpenAI, Anthropic, Qwen, DeepSeek, Mistral, Gemini, and open-source models

Google (Gemini)

Go to aistudio.google.dev
Sign in with your Google account
Navigate to API keys
Create and copy your key

Models available: Gemini Pro

API keys are like passwords. Never share them publicly, commit them to Git, or paste them in chat messages.

The Secrets API

Tesslate provides a dedicated Secrets API for managing your keys programmatically:

Endpoint	Method	Description
`/api/secrets/api-keys`	GET	List all your API keys (values hidden)
`/api/secrets/api-keys`	POST	Add a new API key
`/api/secrets/api-keys/{id}`	PUT	Update an existing key
`/api/secrets/api-keys/{id}`	DELETE	Remove a key
`/api/secrets/api-keys/{id}?reveal=true`	GET	Reveal the decrypted key value
`/api/secrets/providers`	GET	List supported providers

Key Storage Model

Each API key is stored in the UserAPIKey table:

Field	Description
`provider`	Provider identifier: `openrouter`, `anthropic`, `openai`, `google`, `github`
`auth_type`	Type of credential: `api_key`, `oauth_token`, `bearer_token`, `personal_access_token`
`key_name`	Optional user-friendly label
`encrypted_value`	The actual key, encrypted with Fernet
`is_active`	Whether the key is currently in use
`last_used_at`	Timestamp of last usage

Authentication and CSRF Protection

Tesslate uses a dual authentication system with CSRF protection for cookie-based sessions.

Authentication Methods

JWT Token Auth
Cookie-Based OAuth Auth

The primary authentication method. After login, a JWT token is stored in localStorage and sent as a Bearer token in the Authorization header on every request.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

CSRF Token Flow

For cookie-based authentication, Tesslate includes CSRF (Cross-Site Request Forgery) protection:

Token Fetch

On app load, the frontend calls GET /api/auth/csrf to obtain a CSRF token. The token is stored in memory (not localStorage).

Automatic Injection

For all state-changing requests (POST, PUT, DELETE, PATCH), the Axios interceptor automatically adds the X-CSRF-Token header when using cookie-based auth (no Bearer token present).

Server Validation

The CSRFProtectionMiddleware on the backend validates the token for all non-safe HTTP methods.

Automatic Retry

If a 403 response includes a CSRF error, the frontend automatically re-fetches the CSRF token and retries the request once.

CSRF tokens are only required for cookie-based OAuth sessions. If you use JWT (email/password login), the Bearer token in the Authorization header provides equivalent protection.

Project Environment Variables

Adding Variables

Open Project Settings

In your project, click the Settings icon

Go to Environment

Navigate to the Environment Variables tab

Add Variable

Click Add New Variable

Enter Details

Provide a variable name (e.g., STRIPE_KEY) and its value

Save and Restart

Click Save. Restart the dev server to apply changes.

Using in Code

// Client-side (must use VITE_ prefix)
const apiUrl = import.meta.env.VITE_API_URL

// Server-side (no prefix needed)
const dbUrl = process.env.DATABASE_URL

Never use the VITE_ prefix for secret keys. This exposes them to client-side JavaScript where anyone can read them in the browser.

Naming Conventions

Client-Side Variables

VITE_ prefix required

VITE_API_URL
VITE_STRIPE_PUBLIC_KEY
VITE_FIREBASE_API_KEY
Accessible in the browser

Server-Side Variables

No prefix needed

DATABASE_URL
STRIPE_SECRET_KEY
JWT_SECRET
Backend and API routes only

Credential Scoping: User vs Project

Deployment credentials support two scoping levels:

User-Level Defaults
Project-Level Overrides

When project_id is NULL, the credential serves as your default for all projects. For example, your Vercel account token applies to any project you deploy unless overridden.

When project_id is set, the credential applies only to that specific project. This is useful when you need a different Vercel team or Cloudflare account for a particular project.The system checks for a project-specific credential first, then falls back to the user default.

Security Best Practices

Never Commit Secrets

Do not put keys in code files
Always use environment variables
Add .env to .gitignore
Commit only .env.example with placeholder values

Rotate Keys Regularly

Change API keys periodically
Rotate immediately if a team member leaves
Update keys if potentially exposed
Use different keys per environment (dev, staging, production)

Limit Key Permissions

Use read-only keys when possible
Restrict API key scopes to the minimum required
Set usage limits on provider dashboards
Monitor usage for unexpected spikes

Encryption Details

All credentials use Fernet symmetric encryption:

Encryption key stored in the ENCRYPTION_KEY environment variable on the server
Keys are decrypted only at the moment of use (during API calls)
Decrypted values are never logged or cached

Troubleshooting

Variable Not Working

Problem: Cannot access an environment variable in codeSolutions:

Check the variable name spelling
Ensure the VITE_ prefix is present for client-side access
Restart the development server after changes
Verify the variable is saved in project settings

API Key Invalid

Problem: API key returns authentication errorsSolutions:

Verify the key is correct with no extra spaces or newlines
Check the key has not expired
Ensure you have sufficient credits with the provider
Verify the key has the correct scopes and permissions
Try regenerating the key from the provider dashboard

CSRF Token Error

Problem: Receiving 403 errors with CSRF messagesSolutions:

The app automatically retries once after re-fetching the token
If persistent, try refreshing the page to get a new CSRF token
Clear cookies and log in again
Verify you are not making cross-origin requests without proper CORS headers

Accidentally Committed Secrets

Problem: API keys pushed to a Git repositorySolutions:

Immediately rotate all exposed keys with the provider
Remove the secrets from Git history using git filter-branch or BFG Repo Cleaner
Add .env to .gitignore
Consider using the git-secrets tool to prevent future leaks

Next Steps

Model Management

Configure AI models and understand BYOK routing

External Deployments

Set up deployment credentials for Vercel, Netlify, and Cloudflare

Billing

Understand how BYOK affects your credit usage

GitHub Integration

Keep secrets out of your Git repositories

Get Started

Self-Hosting

Core Concepts

Working with Projects

AI Agents

Advanced Features

Developer Guide

Development

Overview

Encrypted Storage

Per-Project Scoping

BYOK Support

CSRF Protection

Types of Secrets

Managing AI Provider Keys

Adding Your Keys

How BYOK Detection Works

Getting API Keys

The Secrets API

Key Storage Model

Authentication and CSRF Protection

Authentication Methods

CSRF Token Flow

Project Environment Variables

Adding Variables

Using in Code

Naming Conventions

Client-Side Variables

Server-Side Variables

Credential Scoping: User vs Project

Security Best Practices

Troubleshooting

Next Steps

Model Management

External Deployments

Billing

GitHub Integration

Get Started

Self-Hosting

Core Concepts

Working with Projects

AI Agents

Advanced Features

Developer Guide

Development

​Overview

Encrypted Storage

Per-Project Scoping

BYOK Support

CSRF Protection

​Types of Secrets

​Managing AI Provider Keys

​Adding Your Keys

​How BYOK Detection Works

​Getting API Keys

​The Secrets API

​Key Storage Model

​Authentication and CSRF Protection

​Authentication Methods

​CSRF Token Flow

​Project Environment Variables

​Adding Variables

​Using in Code

​Naming Conventions

Client-Side Variables

Server-Side Variables

​Credential Scoping: User vs Project

​Security Best Practices

​Troubleshooting

​Next Steps

Model Management

External Deployments

Billing

GitHub Integration

Overview

Types of Secrets

Managing AI Provider Keys

Adding Your Keys

How BYOK Detection Works

Getting API Keys

The Secrets API

Key Storage Model

Authentication and CSRF Protection

Authentication Methods

CSRF Token Flow

Project Environment Variables

Adding Variables

Using in Code

Naming Conventions

Credential Scoping: User vs Project

Security Best Practices

Troubleshooting

Next Steps