API Key Formats - Dev Kit for AI

Dev Kit for AI uses two distinct key types to authenticate different roles and scopes within the platform. Each key type has a unique prefix, format, and purpose.

Key Types Overview

Developer Keys

Authenticate developer console access and manage projects

API Keys (Project Keys)

Authenticate end-user access to specific projects

Developer Keys

Developer Keys authenticate developers accessing the Cloud Admin console and performing administrative operations.

Developer Keys changed from dk_ prefix to ak_ prefix in v1.5.0. The new format improves consistency across key types.

Format Specification

Prefix: ak_ (API Key) Structure: ak_ + 32 URL-safe characters Character set: Alphanumeric (a-z, A-Z, 0-9) plus hyphen (-) and underscore (_) Example: ak_abc123XYZ-_789def456ghi012jkl345 Total length: 35 characters

3 characters: prefix (ak_)
32 characters: random URL-safe string

Properties

Property	Value
Prefix	`ak_`
Length	35 characters total
Character set	`a-zA-Z0-9-_`
Encoding	URL-safe
Hashing	SHA-256
Storage	Hash + 8-char prefix
Display format	`ak_abc12...`
Scope	Developer account
Limit	10 active keys per developer

Usage

Environment variable:

DEVKIT4AI_DEVELOPER_KEY=ak_abc123XYZ-_789def456ghi012jkl345

HTTP header:

X-Developer-Key: ak_abc123XYZ-_789def456ghi012jkl345

Authentication:

Required for console mode deployment
Used to create and manage projects
Grants access to developer-scoped resources
Can be used alongside project keys for elevated operations

Generation

Developer Keys are generated:

Automatically during developer registration (operator-initiated)
Manually via Cloud Admin console
Via API: POST /api/v1/auth/developer-keys

The full key is displayed once at generation. Only the SHA-256 hash and 8-character prefix are stored in the database.

Security

Full key shown only once during generation
Cannot be retrieved after initial display
Store securely in environment variables
Never commit to version control
Rotate every 90 days

API Keys (Project Keys)

API Keys authenticate end-user access to specific projects. They are also referred to as “Project Keys” in environment variables and some documentation.

Important: Both Developer Keys and Project Keys now use the ak_ prefix as of v1.5.0. The key type is distinguished by its scope (developer account vs specific project), not by prefix.

Format Specification

Prefix: ak_ (API Key) Structure: ak_ + 32 URL-safe characters Character set: Alphanumeric (a-z, A-Z, 0-9) plus hyphen (-) and underscore (_) Example: ak_def456ABC-_012ghi789jkl345mno678 Total length: 35 characters

3 characters: prefix (ak_)
32 characters: random URL-safe string

Properties

Property	Value
Prefix	`ak_`
Length	35 characters total
Character set	`a-zA-Z0-9-_`
Encoding	URL-safe
Hashing	SHA-256
Storage	Hash + 8-char prefix
Display format	`ak_def45...`
Scope	Specific project
Limit	Unlimited per project

Usage

Environment variable:

DEVKIT4AI_PROJECT_KEY=ak_def456ABC-_012ghi789jkl345mno678

The environment variable name uses PROJECT_KEY for clarity. Both Developer Keys and Project Keys use the ak_ prefix as of v1.5.0, distinguished only by their scope.

HTTP header:

X-API-Key: ak_def456ABC-_012ghi789jkl345mno678

Authentication:

Required for project mode deployment (Starter Kit)
Scopes all API requests to a specific project
Used by end-users accessing project resources
Validated against project_id in requests

Generation

API Keys are generated:

Automatically during project creation (default key)
Manually via Cloud Admin console
Via API: POST /api/v1/projects/{project_id}/api-keys

The full key is displayed once at generation. Only the SHA-256 hash and 8-character prefix are stored in the database.

Security

Full key shown only once during generation
Cannot be retrieved after initial display
Store securely in environment variables
Never commit to version control
Rotate every 90 days
Revoke immediately if compromised

Key Comparison

Feature	Developer Key (`ak_`)	API Key (`ak_`)
Purpose	Developer console access	End-user project access
Prefix	`ak_`	`ak_`
Character set	Alphanumeric + `-` + `_`	Alphanumeric + `-` + `_`
Length	35 characters	35 characters
Scope	Developer account	Specific project
Limit	10 per developer	Unlimited per project
Header	`X-Developer-Key`	`X-API-Key`
Env var	`DEVKIT4AI_DEVELOPER_KEY`	`DEVKIT4AI_PROJECT_KEY`
Used in	Console mode, operator mode	Project mode

Both key types now use identical format (ak_ prefix + 32 URL-safe characters). The distinction is in their scope and usage, not their format.

Validation Rules

Length Validation

Both key types must:

Be exactly 35 characters long
Start with correct prefix (dk_ or ak_)
Contain 32 random characters after prefix

Character Set Validation

Developer Keys (ak_):

^ak_[a-zA-Z0-9_-]{32}$

API Keys (ak_):

^ak_[a-zA-Z0-9_-]{32}$

Both key types use identical validation regex as of v1.5.0. The system distinguishes key types by their database associations (developer_id vs project_id), not by format differences.

Backend Validation

The backend performs these checks:

Minimum length: At least 16 characters (during validation)
Prefix check: Correct prefix for key type
Hash lookup: SHA-256 hash exists in database
Active status: Key is marked as active
Scope validation: Key matches required scope (developer/project)

Display Format

Keys are displayed in truncated format for security: Full key (shown once):

ak_abc123XYZ-_789def456ghi012jkl345

Displayed format:

ak_abc12...

Only the first 8 characters (including prefix) are stored in the key_prefix field and shown in user interfaces.

Storage Architecture

Database Schema

Both key types follow the same storage pattern: DeveloperKey Table:

CREATE TABLE developer_keys (
    id UUID PRIMARY KEY,
    developer_id UUID NOT NULL,
    key_hash VARCHAR(255) UNIQUE NOT NULL,  -- SHA-256 of full key
    key_prefix VARCHAR(20),                  -- First 8 chars
    name VARCHAR(255),
    is_active BOOLEAN DEFAULT TRUE,
    last_used_at TIMESTAMP,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);

ApiKey Table:

CREATE TABLE api_keys (
    id UUID PRIMARY KEY,
    project_id UUID NOT NULL,
    key_hash VARCHAR(255) UNIQUE NOT NULL,  -- SHA-256 of full key
    key_prefix VARCHAR(20),                  -- First 8 chars
    name VARCHAR(255),
    is_active BOOLEAN DEFAULT TRUE,
    last_used_at TIMESTAMP,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);

Security Implementation

Generation: Random cryptographically secure string
Display: Full key shown once in API response
Hashing: SHA-256 hash computed immediately
Storage: Only hash and prefix persisted to database
Validation: Incoming keys hashed and compared against stored hash

Best Practices

Key Management

Generate separate keys for each environment (dev, staging, production)
Use descriptive names when creating keys
Document which keys are used where
Maintain an inventory of active keys

Security

Store keys in environment variables, never in code
Use hosting provider secrets management for production
Rotate keys every 90 days as a best practice
Revoke compromised keys immediately
Never log full keys, only prefixes

Deployment

Set DEVKIT4AI_DEVELOPER_KEY for console mode
Set both DEVKIT4AI_DEVELOPER_KEY and DEVKIT4AI_PROJECT_KEY for project mode
Validate key format before deployment
Test with new keys before revoking old ones

Troubleshooting

Verify correct prefix (dk_ vs ak_)
Check key length (must be 35 characters)
Confirm key is marked as active in Cloud Admin
Ensure environment variables are loaded correctly
Check that key matches the required scope

Code Examples

Validating Key Format (TypeScript)

function isValidApiKey(key: string): boolean {
  return /^ak_[a-zA-Z0-9_-]{32}$/.test(key)
}

// Usage for both Developer Keys and Project Keys
const devKey = 'ak_abc123XYZ-_789def456ghi012jkl345'
console.log(isValidApiKey(devKey)) // true

const projectKey = 'ak_def456ABC-_012ghi789jkl345mno678'
console.log(isValidApiKey(projectKey)) // true

Since v1.5.0, both Developer Keys and Project Keys use the same format validation. Scope differentiation happens at the database level, not format level.

Environment Configuration

.env.local

# Console mode - requires developer key only
DEVKIT4AI_MODE=console
DEVKIT4AI_DEVELOPER_KEY=ak_abc123XYZ-_789def456ghi012jkl345

# Project mode - requires all three keys
DEVKIT4AI_MODE=project
DEVKIT4AI_DEVELOPER_KEY=ak_abc123XYZ-_789def456ghi012jkl345
DEVKIT4AI_PROJECT_ID=550e8400-e29b-41d4-a716-446655440000
DEVKIT4AI_PROJECT_KEY=ak_def456ABC-_012ghi789jkl345mno678

Making API Requests

// Developer-scoped request
const response = await fetch(`${API_URL}/api/v1/projects`, {
  headers: {
    'X-Developer-Key': process.env.DEVKIT4AI_DEVELOPER_KEY,
    'X-User-Role': 'developer'
  }
})

// Project-scoped request
const response = await fetch(`${API_URL}/api/v1/generations`, {
  headers: {
    'X-Developer-Key': process.env.DEVKIT4AI_DEVELOPER_KEY,
    'X-Project-ID': process.env.DEVKIT4AI_PROJECT_ID,
    'X-API-Key': process.env.DEVKIT4AI_PROJECT_KEY,
    'X-User-Role': 'end_user'
  }
})

Creating Developer Keys

Generate developer keys in Cloud Admin

Creating Project Keys

Generate API keys for projects

Environment Variables

Configure keys in your deployment

Security Settings

Security best practices for keys

Architecture

Configuration

Best Practices

​Key Types Overview

Developer Keys

API Keys (Project Keys)

​Developer Keys

​Format Specification

​Properties

​Usage

​Generation

​Security

​API Keys (Project Keys)

​Format Specification

​Properties

​Usage

​Generation

​Security

​Key Comparison

​Validation Rules

​Length Validation

​Character Set Validation

​Backend Validation

​Display Format

​Storage Architecture

​Database Schema

​Security Implementation

​Best Practices

​Code Examples

​Validating Key Format (TypeScript)

​Environment Configuration

​Making API Requests

​Related Documentation

Creating Developer Keys

Creating Project Keys

Environment Variables

Security Settings

Key Types Overview

Developer Keys

Format Specification

Properties

Usage

Generation

Security

API Keys (Project Keys)

Format Specification

Properties

Usage

Generation

Security

Key Comparison

Validation Rules

Length Validation

Character Set Validation

Backend Validation

Display Format

Storage Architecture

Database Schema

Security Implementation

Best Practices

Code Examples

Validating Key Format (TypeScript)

Environment Configuration

Making API Requests

Related Documentation