---
title: "API Keys hooks"
description: "React hooks for API keys — list, get, create, delete."
section: "Libraries"
group: "React hooks"
order: 402
---

## Usage

```tsx
import Aeontel from "@aeontel/sdk";
import { AeontelProvider, useListApiKeys } from "@aeontel/react";

const client = new Aeontel(import.meta.env.VITE_AEONTEL_API_KEY);

function App() {
  return (
    <AeontelProvider client={client}>
      <ApiKeysList workspaceId="wsp_abc123" />
    </AeontelProvider>
  );
}

function ApiKeysList({ workspaceId }: { workspaceId: string }) {
  const { data, isLoading } = useListApiKeys({ workspace_id: workspaceId });
  if (isLoading) return <p>Loading…</p>;
  return (
    <ul>
      {data?.data.map((k) => (
        <li key={k.id}>{k.name}</li>
      ))}
    </ul>
  );
}
```

## Hooks

### `useCreateApiKey` `mutation`

Create a new API key. Auto-invalidates API key queries on success.

```ts
useCreateApiKey(options?: MutationOpts<ApiKeyCreated, CreateApiKeyParams>)
```

**Types:** [ApiKeyCreated](/types/api-key-created) · [CreateApiKeyParams](/types/create-api-key-params)

```ts
const create = useCreateApiKey();
create.mutate({ workspaceId: "wsp_abc123", name: "CI token" });
```

### `useDeleteApiKey` `mutation`

Delete an API key. Auto-invalidates API key queries on success.

```ts
useDeleteApiKey(options?: MutationOpts<SuccessResponse, string>)
```

**Types:** [SuccessResponse](/types/success-response)

```ts
const del = useDeleteApiKey();
del.mutate("apikey_abc123");
```

### `useListApiKeys` `query`

Fetch paginated list of API keys. Supports workspace_id filter.

```ts
useListApiKeys(params?: Omit<ListApiKeysParams, | > & { filter?: ApiKeyFilter; orderBy?: ApiKeyOrderBy[]; } & ApiKeyShorthands, options?: QueryOpts<Page<ApiKey>>)
```

**Types:** [ListApiKeysParams](/types/list-api-keys-params) · [ApiKeyFilter](/types/api-key-filter) · [ApiKeyOrderBy](/types/api-key-order-by) · [ApiKeyShorthands](/types/api-key-shorthands) · [Page](/types/page) · [ApiKey](/types/api-key)

```ts
const { data } = useListApiKeys({ workspace_id: "wsp_abc123" });
```

### `usePurgeApiKey` `composite`

Permanently delete a soft-deleted API key. Caller must have admin tier.

```ts
usePurgeApiKey(options?: MutationOpts<SuccessResponse, PurgeApiKeyParams>)
```

**Types:** [SuccessResponse](/types/success-response) · [PurgeApiKeyParams](/types/purge-api-key-params)

### `useRestoreApiKey` `composite`

Restore a soft-deleted API key. Auto-invalidates API key queries.

```ts
useRestoreApiKey(options?: MutationOpts<ApiKey, string>)
```

**Types:** [ApiKey](/types/api-key)

### `useRetrieveApiKey` `query`

Fetch a single API key by ID.

```ts
useRetrieveApiKey(id: string, options?: QueryOpts<ApiKey>)
```

**Types:** [ApiKey](/types/api-key)

```ts
const { data: key } = useRetrieveApiKey("apikey_abc123");
```

### `useRotateApiKey` `composite`

Regenerate an API key's secret. The previous key is invalidated and the new
plaintext value is returned in the mutation result. Auto-invalidates queries.

```ts
useRotateApiKey(options?: MutationOpts<ApiKeyCreated, RotateApiKeyParams>)
```

**Types:** [ApiKeyCreated](/types/api-key-created) · [RotateApiKeyParams](/types/rotate-api-key-params)

```ts
const roll = useRotateApiKey({
  onSuccess: (rolled) => showOnce(rolled.key),
});
roll.mutate({ id: "apikey_abc" });
```

### `useUpdateApiKey` `mutation`

Update an API key (e.g. rename). Auto-invalidates API key queries on success.

```ts
useUpdateApiKey(options?: MutationOpts<ApiKey, UpdateApiKeyParams>)
```

**Types:** [ApiKey](/types/api-key) · [UpdateApiKeyParams](/types/update-api-key-params)

```ts
const update = useUpdateApiKey();
update.mutate({ id: "apikey_abc", name: "CI deploy key" });
```