# auth.md for SelfPing

SelfPing authenticates API and MCP traffic with a long-lived bearer token: a SelfPing API key. There is no OAuth authorization server and no dynamic client registration, so an agent cannot provision its own credential. A human issues the key and hands it to the agent.

## How a key is issued

1. A person signs in at https://www.selfping.com/login with their phone number and a one-time code.
2. They open https://www.selfping.com/dashboard and click **New API Key**.
3. The key is shown once on that page and can be copied from there at any time.

The key is bound to the phone number that created it. That binding is what a SelfPing key authorizes: sending a text to that one number. A key cannot be pointed at a different recipient, so a leaked key cannot be used to message third parties.

## Using the key

Send it as a bearer token.

```bash
curl -X POST https://www.selfping.com/api/sms \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SELFPING_API_KEY" \
  -d '{"message": "Deploy finished"}'
```

The same token authenticates the MCP server at https://www.selfping.com/api/mcp.

## Handling the key

Read it from the `SELFPING_API_KEY` environment variable or your platform's secret store. Do not embed it in client-side code, prompts, or committed files. If it is missing, direct the user to https://www.selfping.com/dashboard rather than asking them to paste it into a chat.

## Scopes and limits

Keys are unscoped: one key, one capability, one phone number. Quota is enforced as credits, 10 per month on the free tier, refilling on the 1st. A key that is out of credits returns `403`.

## Revocation

Keys are revoked from https://www.selfping.com/dashboard. There is no programmatic revocation endpoint.

## Machine-readable metadata

- Protected resource metadata (RFC 9728): https://www.selfping.com/.well-known/oauth-protected-resource
- OpenAPI description: https://www.selfping.com/openapi.json
- API catalog: https://www.selfping.com/.well-known/api-catalog
- MCP server card: https://www.selfping.com/.well-known/mcp/server-card.json

The protected resource metadata deliberately omits `authorization_servers`, because SelfPing does not run one. It records that both endpoints take a bearer token in the `Authorization` header and points at this document for how to obtain one.