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

# Authentication

> Create an API key in the dashboard and authenticate requests with a bearer token.

Every request to the HalfPage API is authenticated with an **API key** sent as a
bearer token in the `Authorization` header:

```http theme={null}
Authorization: Bearer hp_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

Requests without a valid key receive `401`.

## Create an API key

Keys are created in the **HalfPage dashboard** — they cannot be minted through
the API.

<Steps>
  <Step title="Open the dashboard">
    Sign in at [halfpagetechnologies.com](https://halfpagetechnologies.com) and
    go to **Settings → API Keys**.
  </Step>

  <Step title="Create a key">
    Only **organization admins** can create, list, or revoke keys. Give the key
    a descriptive name (and, optionally, an expiry date).
  </Step>

  <Step title="Copy it immediately">
    The full key (`hp_live_…`) is shown **once, at creation, and never again**.
    Copy it and store it in a secret manager right away. If you lose it, revoke
    it and create a new one.
  </Step>
</Steps>

## Use the key

Send the key as a bearer token on every request. For example, listing the
available models:

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.halfpagetechnologies.com/backend/api/v1/models \
    -H "Authorization: Bearer $HALFPAGE_API_KEY"
  ```

  ```python Python theme={null}
  import os
  import requests

  BASE_URL = "https://api.halfpagetechnologies.com/backend/api/v1"
  session = requests.Session()
  session.headers["Authorization"] = f"Bearer {os.environ['HALFPAGE_API_KEY']}"

  resp = session.get(f"{BASE_URL}/models")
  resp.raise_for_status()
  print(resp.json())
  ```
</CodeGroup>

<Tip>
  Keep the key in an environment variable (e.g. `HALFPAGE_API_KEY`) rather than
  hard-coding it. Never commit it to source control or expose it in client-side
  code.
</Tip>

## What a key can access

A key is scoped to the **organization** that owns it. Every image, job, and
segmentation you create or read is confined to that organization — you can never
reach another org's data with your key.

Keys work **only on the public product surface**:

<CardGroup cols={2}>
  <Card title="Reachable with an API key" icon="check">
    `upload` · `job` · `image` · `segmentation` · `export` · `models`
  </Card>

  <Card title="Dashboard (browser) only" icon="lock">
    Organization & member management, billing, API-key management, and platform
    admin.
  </Card>
</CardGroup>

Using a valid key against an endpoint outside the product surface returns `403`
(`"API keys cannot access this endpoint"`). API keys also cannot manage API keys —
key creation and revocation require an admin browser session.

## Key lifetime

A key stops working when any of the following happens:

* It is **revoked** from the dashboard.
* Its optional **expiry date** passes.
* The **admin who created it leaves the organization** — a key never outlives its
  creator's membership.

<Warning>
  Treat API keys like passwords. Anyone with your key can run analyses and read
  your organization's data, metered against your plan. Rotate keys periodically
  and revoke any key you suspect has been exposed.
</Warning>