# here.now auth.md

This file tells agents how to sign up for here.now and authenticate API requests.

here.now supports agent-assisted API key creation with an email code. It does not currently support agent-verified ID-JAG registration, OAuth client registration, MCP auth, or third-party identity provider assertions.

## 1. Decide whether authentication is needed

Use no authentication when the user only needs a temporary anonymous Site.

- Anonymous Sites expire after 24 hours.
- Anonymous Sites have lower limits.
- Anonymous Sites can be claimed later by a signed-in user using the claim URL returned by the publish API.

Use an API key when the user needs account-owned resources:

- permanent Sites
- higher limits
- Drives
- Drive share tokens
- custom domains, handles, links, variables, passwords, profiles, billing, or support APIs

## 2. Request an email code

Ask the user for the email address they want to use for here.now. Then request a one-time sign-in code:

```http
POST /api/auth/agent/request-code HTTP/1.1
Host: here.now
Content-Type: application/json
```

```json
{
  "email": "user@example.com"
}
```

Successful response:

```json
{
  "success": true,
  "requiresCodeEntry": true,
  "expiresAt": "2026-05-22T19:25:00.000Z"
}
```

Ask the user to copy the code from their email and paste it back into the agent.

## 3. Verify the code

Submit the email address and code:

```http
POST /api/auth/agent/verify-code HTTP/1.1
Host: here.now
Content-Type: application/json
```

```json
{
  "email": "user@example.com",
  "code": "ABCD-2345"
}
```

Successful response:

```json
{
  "success": true,
  "email": "user@example.com",
  "apiKey": "API_KEY",
  "isNewUser": false
}
```

If the email is new, here.now creates the account automatically.

## 4. Use the API key

Send the API key as a Bearer token:

```http
Authorization: Bearer API_KEY
```

Agents should store the key securely. For the here.now skill and CLI helpers, the recommended local credentials file is:

```text
~/.herenow/credentials
```

Use file permissions that restrict access to the current user, such as 0600.

## 5. Error recovery

- If the email code is invalid or expired, ask the user to request a new code.
- If a request returns 401, load a valid API key or repeat the email-code flow.
- If a request returns 429, wait before retrying and respect any Retry-After header.
- If docs and live API responses disagree, trust the live API response for active operations.

## 6. Dashboard alternative

The user can also sign in at https://here.now/dashboard and copy their API key from the account dashboard.

## Reference

- Docs: https://here.now/docs
- API reference: https://here.now/openapi.json
- Agent context: https://here.now/llms.txt
- Skill: https://here.now/skill.md
- Pricing and limits: https://here.now/pricing.md
- Support: hello@here.now