> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usesatori.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Create API Key

> Generate a new API key for your account

## `keys.create`

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

## Authentication

```bash theme={null}
Authorization: Bearer <clerk_jwt_token>
```

## Parameters

<ParamField body="name" type="string" required>
  Descriptive name for the API key. Use names that indicate the key's purpose.

  ```typescript theme={null}
  name: 'Production Key'
  name: 'Development Key'
  name: 'Testing Key'
  ```
</ParamField>

## Response

<ResponseField name="id" type="string">
  Internal UUID for the API key record
</ResponseField>

<ResponseField name="clerkUserId" type="string">
  Your Clerk user ID
</ResponseField>

<ResponseField name="clerkKeyId" type="string">
  Clerk's API key ID
</ResponseField>

<ResponseField name="name" type="string">
  The name you provided
</ResponseField>

<ResponseField name="secret" type="string">
  The actual API key secret. **Only returned on creation.**

  <Warning>
    Save this immediately! You won't be able to see it again.
  </Warning>
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of creation
</ResponseField>

## Examples

<CodeGroup>
  ```typescript TypeScript (React) theme={null}
  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>
    );
  }
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.usesatori.sh/trpc/keys.create' \
    -H 'Authorization: Bearer <clerk_jwt_token>' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Production Key"}'
  ```
</CodeGroup>

<ResponseExample>
  ```json Success (200) theme={null}
  {
    "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"
  }
  ```

  ```json Error (400) theme={null}
  {
    "error": {
      "message": "Invalid input: name is required",
      "code": "BAD_REQUEST"
    }
  }
  ```
</ResponseExample>

<Warning>
  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.
</Warning>

## Best Practices

<AccordionGroup>
  <Accordion title="Use descriptive names">
    ```typescript theme={null}
    // ✅ 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' });
    ```
  </Accordion>

  <Accordion title="Create separate keys per environment">
    ```typescript theme={null}
    // 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',
    });
    ```
  </Accordion>

  <Accordion title="Store keys securely">
    ```typescript theme={null}
    // 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
    ```
  </Accordion>
</AccordionGroup>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List API Keys" icon="list" href="/api-reference/keys/list">
    View all your API keys
  </Card>

  <Card title="Revoke API Key" icon="ban" href="/api-reference/keys/revoke">
    Revoke a key
  </Card>

  <Card title="Authentication Guide" icon="key" href="/concepts/authentication">
    Learn about API key security
  </Card>
</CardGroup>