# UptimeGrid — Authentication for Agents

This document tells AI agents and automation how to register, authenticate, and exchange data with the UptimeGrid platform.

## TL;DR

| Need | Endpoint |
|------|----------|
| Register a new tenant | `https://app.uptimegrid.net/signup` |
| Sign in (human) | `https://app.uptimegrid.net/login` |
| Exchange password for JWT | `POST https://api.uptimegrid.net/v1/auth/login` |
| Issue an agent API key | `https://app.uptimegrid.net/agents` |
| Revoke / rotate credentials | `https://app.uptimegrid.net/settings?section=team` |
| OAuth Protected Resource metadata | `https://uptimegrid.net/.well-known/oauth-protected-resource` |
| OAuth Authorization Server metadata | `https://uptimegrid.net/.well-known/oauth-authorization-server` |
| OpenID Connect discovery | `https://uptimegrid.net/.well-known/openid-configuration` |

## Identity model

UptimeGrid supports three identity types:

- **Human** — created via signup or invitation, signs in with email + password, Microsoft Entra ID, or Google Workspace SSO.
- **Agent** — long-lived non-human identity, holds an `api_key`, is scoped to one organization and one set of monitors.
- **Service** — programmatic integrator (CI, automation, third-party agents); also uses `api_key`.

## Credential types

- `jwt` — short-lived bearer issued by `POST /api/v1/auth/login`. Lifetime: 24h. Refresh by re-authenticating.
- `api_key` — long-lived bearer minted in the dashboard. No expiry unless revoked. Send as `Authorization: Bearer <key>`.

## Registering an agent

1. Have an admin sign in to `https://app.uptimegrid.net`.
2. Open **Agents → New Agent** to mint an `api_key`. The key is shown once.
3. Pass the key to the agent runtime via `UPTIMEGRID_API_KEY` (or `agent.config.json`).
4. The agent connects out-bound to `https://ingest.uptimegrid.net` and reports heartbeats.

## Authenticating a service account

There is no separate flow today — issue an `api_key` exactly like an agent and use it from your service. Plan to scope keys narrowly: one key per integration.

## Revocation

- **Self-service:** rotate or delete API keys at `https://app.uptimegrid.net/settings?section=team` or per-agent on the Agents page.
- **JWTs** cannot be revoked individually; sign out invalidates the refresh path and JWTs expire within 24 h.

## Transport requirements

- HTTPS only (HTTP requests are redirected).
- TLS 1.2 minimum; 1.3 preferred.
- All API responses set `X-Content-Type-Options: nosniff` and `Content-Security-Policy: frame-ancestors 'none'`.

## Discovery

Agents that want to discover this site programmatically can read:

- `https://uptimegrid.net/.well-known/api-catalog` — RFC 9727 link set
- `https://uptimegrid.net/.well-known/agent-skills/index.json` — Agent Skills Discovery v0.2.0
- `https://uptimegrid.net/.well-known/mcp/server-card.json` — Model Context Protocol server card
- `https://uptimegrid.net/.well-known/oauth-protected-resource` — RFC 9728 resource metadata