# Statusentry auth.md

How AI agents, scripts and integrations get credentials for the Statusentry API.

## Audience

Agents that act for a Statusentry customer: opening incidents, posting incident updates and
scheduling maintenance on that customer's status page (for example from a monitoring alert,
a deploy pipeline or a chat bot).

Reading public content needs no credentials: the website, `/llms.txt`, `/llms-full.txt` and
Markdown versions of every page (send `Accept: text/markdown`) are open to everyone.

## Service

- API base URL: `https://api.statusentry.com/v1/`
- Resources: incidents (`/v1/incidents`), incident updates (`/v1/incidents/:id/entries`),
  scheduled maintenance (`/v1/maintenances`)
- API reference: https://docs.statusentry.com/incident-api
- OpenAPI description: https://statusentry.com/openapi.json (listed in https://statusentry.com/.well-known/api-catalog)
- Authentication guide: https://docs.statusentry.com/how-to-use-statusentry-api-key-pairs-to-authenticate-your-request
- Plans: the API is included on every paid plan, from Start Up ($9.99/month). New accounts start
  with a 30-day Enterprise trial, no credit card required.

## Supported methods

| Method | Supported |
| --- | --- |
| API key pair (access key + secret key), each request signed with a short-lived HS256 JWT | Yes |
| OAuth 2.0 (authorization server, protected resource metadata) | No |
| Programmatic agent registration (`/agent/auth`, ID-JAG, verified email, anonymous) | No |

## Registration and provisioning

There is no self-service registration endpoint for agents. A person on the customer's team
provisions the credentials:

1. Create an account at https://app.statusentry.com/signup (or log in at https://app.statusentry.com/login).
2. In the admin panel, open **API keys** and create a key pair. You get an **access key** and a
   **secret key**. The secret key is shown only once.
3. Give the key pair to the agent through a secret manager or environment variables
   (for example `STATUSENTRY_ACCESS_KEY` and `STATUSENTRY_SECRET_KEY`).

Agents should not create Statusentry accounts on their own. If no key pair is available, ask the
user to create one as described above.

The key pair identifies the status page, so API paths have no page ID.

## Using the credentials

The secret key never goes over the wire. For each request, create a JWT signed with the secret key:

- Algorithm: `HS256`, signed with the secret key
- `iss`: the access key
- `aud`: `www.statusentry.com`
- `iat`: now, `exp`: a few minutes later (keep tokens short-lived)

Send it in the `Authorization` header together with the access key:

```
Authorization: StatusEntry <ACCESS_KEY>:<SIGNED_JWT>
```

Python example:

```python
import os, time
import jwt        # pip install pyjwt requests
import requests

ACCESS_KEY = os.environ["STATUSENTRY_ACCESS_KEY"]
SECRET_KEY = os.environ["STATUSENTRY_SECRET_KEY"]
API = "https://api.statusentry.com/v1"

def headers():
    now = int(time.time())
    token = jwt.encode({"iss": ACCESS_KEY, "aud": "www.statusentry.com", "iat": now, "exp": now + 300},
                       SECRET_KEY, algorithm="HS256")
    return {"Authorization": f"StatusEntry {ACCESS_KEY}:{token}", "Content-Type": "application/json"}

incidents = requests.get(f"{API}/incidents", headers=headers()).json()
```

## Revoking credentials

Revoke a key pair in the admin panel under **API keys**. To rotate, create a new pair, update the
agent's secrets, then revoke the old pair.

## Contact

Questions about API access: support@statusentry.com