# Authentication (https://hypit.ai/api-reference/authentication/)

> Create an API key, send it as a bearer token, and read the four failure modes apart.

Every call to `/v1` and `/v1beta` is authenticated with an API key that hypit.ai mints for your
account. There is no separate client id, no signature and no expiry unless you set one.

## Getting a key [#getting-a-key]

Sign in at [hypit.ai](https://hypit.ai), open the account dialog and choose the **API Keys** pane.
Creating a key shows you the plaintext exactly once — we store only a SHA-256 digest and the first
four characters, so a key that is lost cannot be recovered, only replaced.

An account may hold up to **50** live keys at a time.

Keys look like this:

```text
sk-hh-x7Kq2mZ4nR8vT1wY6bC0dF3gH5jL9pQs
```

The `sk-` shape is deliberate — it keeps the key compatible with tooling that expects an
OpenAI-style secret. The `hh` marker is what lets a secret scanner, or a support engineer reading a
pasted config, tell a hypit.ai key apart from the dozen other `sk-` shaped things in a project.

<Callout type="warn" title="Treat the key as a bearer credential">
  Anyone holding the key can spend your credits. Keep it server-side, put it in an environment
  variable rather than in source, and delete it from the account dialog the moment you suspect it
  leaked — deletion is immediate.
</Callout>

## Sending it [#sending-it]

The canonical form is an `Authorization` header:

```bash
curl https://hypit.ai/v1/models \
  -H "Authorization: Bearer $HYPIT_API_KEY"
```

Because different vendor SDKs put credentials in different places, four alternatives are accepted
on every route. They are read in this order, and the first non-empty one wins:

| Where                   | Example                           |
| ----------------------- | --------------------------------- |
| `Authorization: Bearer` | `Authorization: Bearer sk-hh-...` |
| `X-Api-Key`             | the Anthropic SDK spelling        |
| `X-Goog-Api-Key`        | the Google GenAI SDK spelling     |
| `Api-Key`               | plain header                      |
| `?key=` query parameter | the Google REST spelling          |

The query parameter exists so an unmodified Google client can reach
[the native Gemini surface](/api-reference/gemini). Prefer a header everywhere else: a query string
ends up in browser history, proxy logs and `Referer` headers.

## Every response is traceable [#every-response-is-traceable]

Each response carries an `X-Request-Id` header. If you send one yourself, we adopt it (up to 128
characters, no newlines) so that your logs and ours name the same request. Quote it in any support
ticket.

```bash
curl -i https://hypit.ai/v1/models \
  -H "Authorization: Bearer $HYPIT_API_KEY" \
  -H "X-Request-Id: my-trace-0001"
```

## Authentication failures [#authentication-failures]

All of them are HTTP `401` with `"type": "authentication_error"`, but the `code` tells you which
switch to flip:

```json
{
  "error": {
    "message": "invalid api key",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}
```

| `code`                 | Meaning                                                |
| ---------------------- | ------------------------------------------------------ |
| `missing_token`        | no credential was found in any of the five places      |
| `invalid_api_key`      | the key does not exist — usually a truncated paste     |
| `key_disabled`         | the key was disabled in the account dialog             |
| `key_expired`          | the key carried an expiry and it has passed            |
| `account_disabled`     | the owning account is suspended                        |
| `identity_unavailable` | HTTP `503`; our directory is briefly unreadable, retry |

A `401` never means "out of credits" — that is a `402`, described in
[Credits and billing](/api-reference/billing).

## Third-party agents [#third-party-agents]

If you are building an application that acts on **other people's** hypit.ai accounts, do not ask
them for their API key. hypit.ai runs an OAuth 2.0 authorization server; an access token minted
through it is accepted on `/v1` exactly like a key, but is scoped per modality, so an agent
approved to caption pictures cannot spend a month of credits on video. Contact us for client
registration.