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

# Authentication

> Creating and using API keys, and keeping them safe.

## API keys

`POST /v1/tts` is authenticated with a **bearer token**:

```
Authorization: Bearer sk-tokay-...
```

Create and manage keys in the [Geko console](https://app.geko.sh). A key is shown **once** at creation — store it then; the server only keeps a hash. (Keys look like `sk-tokay-` followed by 48 hex characters.)

The catalog endpoints — `/v1/models`, `/v1/voices`, `/health` — are **open** and need no key, so docs, playgrounds, and voice pickers can render without one.

## With the SDK

Pass the key explicitly, or let the SDK read it from the environment (`GEKO_API_KEY`, falling back to `TOKAY_API_KEY`):

```ts theme={null}
import { Geko } from "@gekoai/sdk";

const geko = new Geko({ apiKey: "sk-tokay-..." }); // explicit
const geko2 = new Geko();                          // from GEKO_API_KEY
```

```bash theme={null}
export GEKO_API_KEY=sk-tokay-...
```

## Keep keys server-side

<Warning>
  Your API key grants billable usage. **Never ship it to a browser or mobile app.** Anything in client-side code is public.
</Warning>

* Call Geko from your backend (API route, server, worker, function).
* Expose your *own* thin endpoint to your frontend; keep the Geko key on the server.
* Don't put the key in client-side JS, a public repo, or a mobile bundle.

The API now sends permissive CORS headers, so a browser *can* call it cross-origin — but that does **not** make it safe to expose your key. Keep synthesis behind your own server. See [Use it in your app](/guides/frameworks) for a Next.js route example.

## Quotas & billing

Keys are metered per organization. If you run out of credits, `POST /v1/tts` returns **HTTP 429** with a `detail` explaining you're out of credits — top up in the console. The SDK surfaces this as a `GekoError` (`status === 429`) and does **not** retry it (a retry can't create credits). See [Errors & retries](/sdk/errors).

## Rotating a key

Revoke a key in the console and issue a new one. Revocation takes effect within a short caching window (the API caches key lookups for about 30 seconds).

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/quickstart">
    Make your first authenticated request in minutes.
  </Card>

  <Card title="TypeScript SDK" icon="code" href="/sdk/typescript">
    The typed client that reads your key from the environment.
  </Card>

  <Card title="Errors & retries" icon="shield-check" href="/sdk/errors">
    Handle 401, 429, and transient failures cleanly.
  </Card>

  <Card title="Billing & credits" icon="credit-card" href="/billing">
    How usage is metered and what running out looks like.
  </Card>
</CardGroup>