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

# Auth

# `blursec.auth`

Operations on the API key the SDK was constructed with. Useful for diagnostics and key rotation — **not** part of the credential-check hot path.

```ts theme={null}
import { Blursec } from "@blursec/sdk";

const blursec = new Blursec({ apiKey: process.env.BLURSEC_API_KEY! });
```

***

## `whoami() → Promise<AuthPrincipal>`

Returns information about the authenticated principal: which workspace the key belongs to, its scopes, and when it was created. Use this on app boot to verify the SDK is correctly configured.

```ts theme={null}
const me = await blursec.auth.whoami();
console.log("[blursec]", me.workspaceName, "key scopes:", me.scopes);
```

**Endpoint:** `GET /v1/auth/whoami`

**Returns:**

```ts theme={null}
interface AuthPrincipal {
  keyId: string;
  workspaceId: string;
  workspaceName: string;
  scopes: string[];
  createdAt: string;
}
```

***

## `rotate() → Promise<RotatedApiKey>`

Generates a new API key tied to the same principal and **revokes the current key**. The response contains the new key — store it before doing anything else, otherwise you'll lock yourself out.

```ts theme={null}
const rotated = await blursec.auth.rotate();
await secretsStore.put("BLURSEC_API_KEY", rotated.apiKey);

// existing client is now using a revoked key — rebuild
const blursec = new Blursec({ apiKey: rotated.apiKey });
```

**Endpoint:** `POST /v1/auth/rotate`

**Returns:**

```ts theme={null}
interface RotatedApiKey {
  apiKey: string;          // the new key (shown only once)
  keyId: string;
  rotatedAt: string;
}
```

> **Security note:** Treat rotation as a destructive operation. There is no undo. Always confirm the secret was persisted to your secret store *before* taking down the previous client.