Skip to main content

createUserApiKey

Creates a new API key for the authenticated user. This key can be used to authenticate API requests from external applications like the Raycast extension.
Automatic Revocation: Creating a new API key automatically revokes all existing active keys for the user. Only one API key can be active per user at a time.

Parameters

name
string
default:"API Keys"
Optional friendly name for the API key (for display purposes)

Returns

id
Id<'apiKeys'>
Unique identifier for the API key record
name
string
The friendly name of the API key
keyPrefix
string
The 12-character prefix used for identification (e.g., a1b2c3d4e5f6)
key
string
The complete API key in format: teakapi_[prefix]_[secret]
This is the only time you’ll see the complete key. Store it securely - it cannot be retrieved later.
access
'full_access'
Access level granted to this key (currently always full_access)
createdAt
number
Unix timestamp (in milliseconds) when the key was created

Usage

Generate Key in Settings

import { useMutation } from "convex/react";
import { api } from "@teak/convex";

function ApiKeySettings() {
  const createApiKey = useMutation(api.apiKeys.createUserApiKey);
  const [newKey, setNewKey] = useState<string | null>(null);
  
  const handleGenerate = async () => {
    const result = await createApiKey({ name: "My API Key" });
    setNewKey(result.key);
  };
  
  return (
    <div>
      <button onClick={handleGenerate}>Generate New API Key</button>
      
      {newKey && (
        <div>
          <p>Your new API key (save it now):</p>
          <code>{newKey}</code>
          <p>This key will not be shown again.</p>
        </div>
      )}
    </div>
  );
}

Example Response

{
  "id": "jh7x5t9p2k8n4m1q6r3s",
  "name": "API Keys",
  "keyPrefix": "a1b2c3d4e5f6",
  "key": "teakapi_a1b2c3d4e5f6_1234567890abcdef1234567890abcdef1234567890abcdef",
  "access": "full_access",
  "createdAt": 1704067200000
}

Security

Key Format

API keys follow this structure:
teakapi_[prefix]_[secret]
  • Prefix: 12-character hex string (6 random bytes)
  • Secret: 48-character hex string (24 random bytes)
  • Total length: 67 characters

Hashing

Keys are hashed with SHA-256 and a server-side pepper before storage:
hash = SHA256(apiKey + serverPepper)
Only the hash is stored in the database. The original key is never retrievable.

Storage Recommendations

Store API keys in environment variables, never in code:
TEAK_API_KEY=teakapi_a1b2c3d4e5f6_...
Use secret management services in production:
  • AWS Secrets Manager
  • HashiCorp Vault
  • 1Password CLI
  • Doppler
Add to .gitignore:
.env
.env.local
secrets.json

Behavior

Automatic Revocation

When you create a new API key:
  1. All existing active keys for your user are revoked
  2. The new key is created and returned
  3. Old keys become invalid immediately
This ensures only one API key is active at a time per user.

Default Name

If no name is provided, the key is named "API Keys" by default.

Access Levels

Currently, all API keys have full_access, which grants:
  • Full read access to your cards
  • Full write access (create, update, delete cards)
  • File upload permissions
  • Search capabilities
More granular permission levels may be added in future releases.

Error Handling

Authentication Required

{
  "code": "UNAUTHORIZED",
  "error": "Authentication required"
}
This mutation requires an authenticated user session.

List API Keys

View your active and revoked API keys

Revoke API Key

Revoke an existing API key

Authentication

Learn how to use API keys

Build docs developers (and LLMs) love