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

# Authentication

> Use an account API key for scripts, agents, and backend integrations.

Send your API key in the `Authorization` header on every authenticated request:

```bash theme={null}
curl --fail-with-body -sS https://api.phone-harness.com/me \
  -H "Authorization: Bearer $PHONE_HARNESS_API_KEY"
```

## Get your first key

1. Accept your Phone Harness invitation and complete account creation.
2. Sign in with an available GitHub or email method.
3. Open [API keys](https://phone-harness.com/dashboard/api-keys) in the dashboard.
4. Select **Create key**, give it a label, and copy the key.

The full key is shown once. The key list shows only a display hint and its identifier. If you lose it, create a replacement and revoke the old key.

## What a key can access

A key acts as your account. It can manage your sessions and API keys, inspect your account and history, and operate your phones. Keys are not scoped to individual phones and do not have separate read-only permissions.

Another account's session is treated as missing. The API returns `404` rather than exposing who owns it.

> [!WARNING]
>
> An API key is a secret. Do not put it in a share URL, a public repository, frontend code, or a screenshot. Use environment variables or your deployment's secret store.

## Rotate and revoke keys

Use `GET /me/keys` to find a key's `key_hash`, then send that identifier to `POST /me/keys/revoke`:

```bash theme={null}
curl --fail-with-body -sS https://api.phone-harness.com/me/keys/revoke \
  -H "Authorization: Bearer $PHONE_HARNESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key_hash":"REPLACE_WITH_KEY_HASH_FROM_KEY_LIST"}'
```

For rotation, create and test the replacement first. Revoking a key prevents subsequent authentication with that key; it does not end existing phone sessions. End sessions separately when needed.

## Browser sign-in

The Phone Harness dashboard uses a Clerk session token with the same bearer header. For server integrations, use a Phone Harness API key instead of copying a short-lived browser token. Authentication does not bypass invite-only account access.

## Read-only watch links

A session's `watch_url` contains a limited view grant. It can expose that session's metadata, snapshots and live video (view only) while the grant and session remain valid. It cannot install apps, send operations, or obtain the interactive owner viewer.

Treat watch links as private capabilities: anyone holding a valid link can use its granted view access. Never replace its token with your API key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.