Documentation

Everything you need to get started with IBYOK and integrate it into your applications.

Quick Start

Get up and running with IBYOK in just a few minutes.

Sign in with GitHub

Create your IBYOK account using GitHub authentication. No separate password to remember.

Add your API keys

Navigate to API Keys and add your LLM provider keys. Keys are encrypted immediately upon storage.

Create an access token

Generate an access token with the scopes your application needs (e.g., keys:read).

Retrieve keys via API

Use the External API to fetch decrypted keys at runtime. Never store keys in your codebase.

API Example

Retrieve your API key with a simple HTTP request.

Request

# Basic request (uses server's current environment)
curl -X GET "https://api.ibyok.dev/external/keys/{keyId}/value" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# With environment override (dev, staging, or prod)
curl -X GET "https://api.ibyok.dev/external/keys/{keyId}/value?env=dev" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response (development with mock mode)

{
  "keyId": "key_abc123",
  "name": "OpenAI Production",
  "llmType": "openai",
  "value": "sk-mock-openai-abc123def456",
  "modeInfo": {
    "environment": "development",
    "effectiveMode": "mock",
    "source": "tenant_setting"
  }
}

For full API documentation, sign in and visit the API Docs in your dashboard.

Key Concepts

API Keys

Your LLM provider credentials stored with KMS encryption. Each key has a unique ID, name, and provider type.

Access Tokens

Scoped credentials for the External API. Create tokens with specific permissions like keys:read or usage:read.

Mock Mode

Return fake key values for testing. Configure per environment (dev/staging/prod) or override per key.

Frequently Asked Questions

What is IBYOK?

IBYOK (Bring Your Own Keys) is a secure key management service for LLM API keys. It provides encrypted storage, environment-based controls, and a REST API for programmatic access to your keys.

How do I add an API key?

After signing in, go to Dashboard > API Keys and click "Add Key". Enter a name, select the LLM provider type, and paste your key. The key is encrypted with AWS KMS before storage.

What is mock mode?

Mock mode returns fake API key values instead of your real keys. This is useful for development and testing environments where you want to test your integration without making actual LLM API calls.

How do per-key overrides work?

Each key can have its own mock mode setting for each environment (development, staging, production). Key-level overrides take precedence over environment defaults, but infrastructure guardrails always win.

What are the resolution priority levels?

Mode is resolved in this order: 1) Infrastructure guardrails (env vars) - always wins, 2) Per-key override - if set for this key+environment, 3) Environment default - your tenant-level setting.

How do I create an access token?

Go to Dashboard > Access Tokens and click "Create Token". Give it a name, select the scopes it needs (e.g., keys:read), and optionally set an expiration. Copy the token immediately - it won't be shown again.

What scopes are available?

Available scopes include: keys:read (retrieve key values) and usage:read (view usage statistics). Use the minimum scopes required for your use case.

Is there a rate limit?

Your plan determines your monthly API call quota. Free: 250 calls, Starter: 10,000 calls, Premium: 100,000 calls. If you reach your limit, upgrade anytime to continue instantly with no downtime.

How do I retrieve a key via API?

Make a GET request to /external/keys/:keyId/value with your access token in the Authorization header (Bearer token). Optionally include ?env=dev, ?env=staging, or ?env=prod to specify which environment's mock mode settings to use. The response includes the decrypted key value and mode information.

How does the env parameter work?

The optional env query parameter lets you specify which environment's mock mode settings to use when retrieving a key. Valid values are: dev, staging, or prod. If not specified, the server's current environment is used.

What providers are supported?

IBYOK supports 60+ LLM providers including OpenAI, Anthropic, Google, Mistral, Cohere, and many more. You can also add custom provider keys.