> ## 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.

# Revoke API Key

> Permanently revoke an API key

## `keys.revoke`

Revokes an API key, immediately preventing all access. This endpoint requires Clerk JWT authentication.

## Authentication

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

## Parameters

<ParamField body="id" type="string" required>
  UUID of the API key to revoke (from `keys.list`)
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Returns `true` if the key was successfully revoked
</ResponseField>

## Examples

<CodeGroup>
  ```typescript TypeScript (React) theme={null}
  import { trpc } from '@/lib/trpc';

  function RevokeKeyButton({ keyId }: { keyId: string }) {
    const revokeKey = trpc.keys.revoke.useMutation({
      onSuccess: () => {
        alert('API key revoked successfully');
      },
    });
    
    const handleRevoke = () => {
      if (confirm('Are you sure? This cannot be undone.')) {
        revokeKey.mutate({ id: keyId });
      }
    };
    
    return (
      <button onClick={handleRevoke} className="text-red-600">
        Revoke Key
      </button>
    );
  }
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.usesatori.sh/trpc/keys.revoke' \
    -H 'Authorization: Bearer <clerk_jwt_token>' \
    -H 'Content-Type: application/json' \
    -d '{"id":"550e8400-e29b-41d4-a716-446655440000"}'
  ```
</CodeGroup>

<ResponseExample>
  ```json Success (200) theme={null}
  {
    "success": true
  }
  ```

  ```json Error (404) theme={null}
  {
    "error": {
      "message": "API key not found",
      "code": "NOT_FOUND"
    }
  }
  ```

  ```json Error (401) theme={null}
  {
    "error": {
      "message": "Unauthorized - API key does not belong to you",
      "code": "UNAUTHORIZED"
    }
  }
  ```
</ResponseExample>

<Warning>
  Revoking a key immediately stops all applications using that key. Make sure to update your applications with a new key before revoking the old one.
</Warning>

## Key Rotation Workflow

<Steps>
  <Step title="Create a new API key">
    ```typescript theme={null}
    const newKey = await createKey.mutate({
      name: 'Production Key (New)',
    });

    console.log('New key:', newKey.secret);
    ```
  </Step>

  <Step title="Update your applications">
    Update environment variables in all environments:

    ```bash theme={null}
    # .env.production
    SATORI_API_KEY=sk_satori_new_key...
    ```

    Deploy the updates to all services.
  </Step>

  <Step title="Verify the new key works">
    Test your application to ensure the new key is working correctly.
  </Step>

  <Step title="Revoke the old key">
    ```typescript theme={null}
    await revokeKey.mutate({ id: oldKeyId });
    ```

    <Check>
      Old key is now revoked and cannot be used.
    </Check>
  </Step>
</Steps>

## Use Cases

<AccordionGroup>
  <Accordion title="Compromised key">
    If you suspect a key has been exposed:

    ```typescript theme={null}
    // Immediately revoke the compromised key
    await revokeKey.mutate({ id: compromisedKeyId });

    // Create a new key
    const newKey = await createKey.mutate({
      name: 'Production Key (Rotated)',
    });

    // Update your applications ASAP
    ```
  </Accordion>

  <Accordion title="Unused keys">
    Clean up keys that are no longer in use:

    ```typescript theme={null}
    const keys = await client.keys.list.query();

    for (const key of keys) {
      // If not used in 90 days
      const ninetyDaysAgo = Date.now() - 90 * 24 * 60 * 60 * 1000;
      const lastUsed = key.lastUsedAt ? new Date(key.lastUsedAt).getTime() : 0;
      
      if (lastUsed < ninetyDaysAgo) {
        await revokeKey.mutate({ id: key.id });
        console.log(`Revoked unused key: ${key.name}`);
      }
    }
    ```
  </Accordion>

  <Accordion title="Employee offboarding">
    Revoke keys when team members leave:

    ```typescript theme={null}
    // Revoke all keys associated with a project
    const keysToRevoke = [
      'key-id-1',
      'key-id-2',
      'key-id-3',
    ];

    for (const keyId of keysToRevoke) {
      await revokeKey.mutate({ id: keyId });
    }
    ```
  </Accordion>
</AccordionGroup>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List API Keys" icon="list" href="/api-reference/keys/list">
    Find keys to revoke
  </Card>

  <Card title="Create API Key" icon="plus" href="/api-reference/keys/create">
    Create a replacement key
  </Card>

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