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

# blobhub-worker login

> Store the API key and validate identity

`blobhub-worker login` is the first-run setup command. It stores your BlobHub API key, pulls your
user profile from BlobHub to validate the key, and records the resulting durable identity.

## Synopsis

```bash theme={null}
blobhub-worker login
```

No flags.

## What it does

1. Prompts for an optional **BlobHub API URL** (default `https://api.blobhub.io/v1`; press Enter to
   accept).
2. Prompts for your **BlobHub API key** (read with `getpass`, so it is not echoed to the terminal).
3. Calls `GET /v1/users/me` with the supplied key to validate it and retrieve your `user_id`,
   `name`, and `email`.
4. Writes `~/.blobhub-worker/credentials.yaml` with mode `0600`:
   ```yaml theme={null}
   api:
     key: bhk_...
     url: https://api.blobhub.io/v1
   ```
5. Writes (or refreshes) `~/.blobhub-worker/identity.yaml`:
   ```yaml theme={null}
   user:
     user_id: usr_01J...
     name: Your Name
     email: you@example.com
     recorded_at: 2026-05-27T12:34:56Z
   ```

The command is idempotent — running it again with the same key is a no-op refresh.

## Identity-change guard

If `identity.yaml` already records a `user_id` and the new API key resolves to a **different**
`user_id`, the command warns and requires explicit confirmation before overwriting. This protects
against silently swapping the actor identity by switching credentials.

## Errors

| Code                               | Meaning                                                                                           |
| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
| `AUTH_INVALID`                     | The server rejected the API key (401/403 from `/v1/users/me`).                                    |
| `USER_IDENTITY_MISMATCH`           | The server's `user_id` differs from the previously recorded value, and confirmation was declined. |
| `INSECURE_CREDENTIALS_PERMISSIONS` | `credentials.yaml` exists but is world-readable (refused).                                        |

Full descriptions: [Reference](/worker/reference).

## Recommendation

For production use, create a **dedicated service-account user** in BlobHub and use that user's API
key for the worker. Some job types (notably
[Session Agent Harness](/worker/session-agent-harness/overview)) classify any post made by the
worker's own `user_id` as "self" and filter it out — running under a dedicated identity keeps
your own posts from being silently dropped. See the
[Session Agent Harness reference](/worker/session-agent-harness/reference) for details.

## See also

* [`blobhub-worker start`](/worker/cli/start)
* [Filesystem layout](/worker/filesystem)