Skip to main content

​
keys.create

Creates a new API key. This endpoint requires Clerk JWT authentication.

​
Authentication

Authorization: Bearer <clerk_jwt_token>

​
Parameters

​
name
string
required
Descriptive name for the API key. Use names that indicate the key’s purpose.
name: 'Production Key'
name: 'Development Key'
name: 'Testing Key'

​
Response

​
id
string
Internal UUID for the API key record
​
clerkUserId
string
Your Clerk user ID
​
clerkKeyId
string
Clerk’s API key ID
​
name
string
The name you provided
​
secret
string
The actual API key secret. Only returned on creation.
Save this immediately! You won’t be able to see it again.
​
createdAt
string
ISO 8601 timestamp of creation

​
Examples

import { trpc } from '@/lib/trpc';

function CreateKeyButton() {
  const createKey = trpc.keys.create.useMutation({
    onSuccess: (data) => {
      // Show the secret to the user
      alert(`Your API key: ${data.secret}\n\nSave this now!`);
    },
  });
  
  const handleCreate = () => {
    const name = prompt('Enter a name for this key:');
    if (name) {
      createKey.mutate({ name });
    }
  };
  
  return (
    <button onClick={handleCreate}>
      Create New API Key
    </button>
  );
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "clerkUserId": "user_372Icb...",
  "clerkKeyId": "key_2abc123...",
  "name": "Production Key",
  "secret": "sk_satori_abc123def456...",
  "createdAt": "2024-01-15T10:30:00.000Z"
}
The secret field is only returned when creating a key. Store it securely immediately. If you lose it, you’ll need to create a new key.

​
Best Practices

// ✅ Good: Clear purpose
await createKey.mutate({ name: 'Production - Web App' });
await createKey.mutate({ name: 'Development - Local' });
await createKey.mutate({ name: 'CI/CD Pipeline' });

// ❌ Bad: Vague names
await createKey.mutate({ name: 'Key 1' });
await createKey.mutate({ name: 'Test' });

// Production
const prodKey = await createKey.mutate({
  name: 'Production Environment',
});

// Staging
const stagingKey = await createKey.mutate({
  name: 'Staging Environment',
});

// Development
const devKey = await createKey.mutate({
  name: 'Development Environment',
});

// After creating a key
const newKey = await createKey.mutate({ name: 'Production Key' });

// ✅ Store in environment variables
console.log('Add this to your .env file:');
console.log(`SATORI_API_KEY=${newKey.secret}`);

// ❌ Don't commit to version control
// ❌ Don't store in client-side code
// ❌ Don't share via insecure channels

List API Keys

View all your API keys

Revoke API Key

Revoke a key

Authentication Guide

Learn about API key security