# auth.md

Not an agent? You might be looking for [peppolstatus.com](https://peppolstatus.com/).

You are an agent. This document tells you how authentication works for the
**PeppolStatus public API** (`https://api.peppolstatus.com`).

## Discover

This file covers authentication for the PeppolStatus public API. The API is
read-only and requires **no authentication** — you can call every endpoint
right now, without registering anything.

There is **no OAuth authorization server** and **no dynamic client
registration**. No `/.well-known/oauth-authorization-server` or
`/.well-known/oauth-protected-resource` endpoints are published, and none of
the flows defined by the auth.md convention (agent verified, user claimed)
are offered. Do not attempt an OAuth flow against this domain.

The machine-readable spec is at `https://api.peppolstatus.com/openapi.json`;
a quickstart is at [https://peppolstatus.com/api.md](https://peppolstatus.com/api.md).

## Pick a method

Two options:

1. **Anonymous (default).** No credential needed. All endpoints are
   GET/HEAD/OPTIONS:

   ```http
   GET /v1/network HTTP/1.1
   Host: api.peppolstatus.com
   ```

2. **Optional API key.** Used today for attribution and rate-limit purposes
   only; paid tiers are planned.

## Register

There is no dynamic client registration and no agent registration endpoint.
If your user wants attribution or higher/paid tiers later, they can create a
free account — this is a **human sign-up form**, not an agent registration
flow:

1. Sign up at [https://app.peppolstatus.com/sign-up](https://app.peppolstatus.com/sign-up).
2. An API key is issued instantly. Format: `pps_live_…` (production) or `pps_test_…` (test).

## Claim

Not offered. No user-claimed flow exists for this API.

## Use the credential

Send the API key as a bearer token:

```http
GET /v1/hosts HTTP/1.1
Host: api.peppolstatus.com
Authorization: Bearer pps_live_...
```

## Errors

- A missing or invalid key never causes a 401 today — the API accepts
  anonymous requests everywhere.
- Request errors are returned as RFC 9457 `application/problem+json`.
- Rate limit: 60 requests / 60s per client identity, reported via
  `RateLimit-*` response headers.

## Revocation

Keys are managed (created, revoked) at
[https://app.peppolstatus.com/keys](https://app.peppolstatus.com/keys).

## Support

Email [hello@peppolstatus.com](mailto:hello@peppolstatus.com).
PeppolStatus is built by [e-invoice.be](https://e-invoice.be).