# auth.md — Authenticating with HIIE

> How an agent or script authenticates to the HIIE v1 API and MCP server.

## TL;DR — use an API key

The headless HIIE surface (`/api/v1/*` and the MCP server at `/api/mcp`)
authenticates with a **HIIE API key**, sent as a Bearer token:

```
Authorization: Bearer hk_live_<id>.<secret>
```

1. Sign in at https://hiie.arthurlabs.net/connect.
2. Mint a key at https://hiie.arthurlabs.net/account. Choose its scopes (`read`, `write`,
   `build`). The secret is shown **once** — store it securely.
3. Send it on every request. Keys are owner-scoped: a key only ever sees the
   tenant it was minted for.

Revoke a key any time at https://hiie.arthurlabs.net/account.

## Discovery

- **Protected-resource metadata** (RFC 9728): https://hiie.arthurlabs.net/.well-known/oauth-protected-resource
- **API catalog** (RFC 9727): https://hiie.arthurlabs.net/.well-known/api-catalog
- **OpenAPI security scheme:** `apiKey` (HTTP Bearer) in https://hiie.arthurlabs.net/.well-known/openapi.json

A `401` response carries a `WWW-Authenticate: Bearer` header whose
`resource_metadata` parameter points at the protected-resource document above.

## About OAuth / Clerk

The tenant's **interactive** identity provider is [Clerk](https://clerk.com),
which is the OAuth/OIDC authorization server referenced by the protected-resource
metadata. **The v1 API and MCP server do not currently accept Clerk-issued OAuth
access tokens** — programmatic access is via HIIE API keys as described above.
If OAuth-token access to the API is enabled in the future, it will be announced
here and reflected in the discovery documents.

## Scopes

| Scope | Grants |
| --- | --- |
| `read` | List projects, poll builds, list designs/templates/artifacts, download files |
| `write` | Create projects, write artifacts |
| `build` | Start builds, generate CAD, run flows |

`admin` implies all scopes. Grant the least privilege an agent needs.

## Contact

support@arthurlabs.net