# Eventi API authentication (auth.md)

> How to authenticate to the Eventi public API. Developer hub: https://ueventi.com/developers

Eventi exposes a small set of public endpoints that need no credentials at all. They are open to anyone and rate limited by IP. There are no self-serve API keys yet - everything else on the platform (guest lists, sending invitations over WhatsApp, RSVP tracking) is session-authenticated through the dashboard.

## Audience

Developers and AI agents that want to call Eventi's public endpoints - today, the invitation-card renderer and a health check.

## Discover

Machine-readable metadata for the API:

- OpenAPI spec (JSON): https://ueventi.com/openapi.json
- OpenAPI spec (YAML): https://ueventi.com/openapi.yaml
- API catalog (RFC 9727): https://ueventi.com/.well-known/api-catalog
- MCP server card: https://ueventi.com/.well-known/mcp/server-card.json
- Agent skills index: https://ueventi.com/.well-known/agent-skills/index.json
- Site index for agents: https://ueventi.com/llms.txt
- This document: https://ueventi.com/auth.md

## OAuth discovery metadata

- oauth-protected-resource (RFC 9728): https://ueventi.com/.well-known/oauth-protected-resource - published today. Its `authorization_servers` list is empty because no authorization server exists yet.
- oauth-authorization-server (RFC 8414): not published. There is no OAuth authorization server, no token endpoint, and no dynamic client registration today.
- 401 responses from https://app.ueventi.com/api/v1 carry `WWW-Authenticate: Bearer resource_metadata="https://ueventi.com/.well-known/oauth-protected-resource"` so agents can discover this metadata from an unauthenticated probe.

## Pick a method

There is one thing to know today: the public endpoints need no credentials.

- No API key, no token, no header. Just call the endpoint.
- Requests are rate limited by IP. The invitation renderer allows 30 requests per hour per IP.
- CORS is open (`Access-Control-Allow-Origin: *`), so the renderer can be called directly from a browser.

The rest of Eventi - creating events, importing a guest list, sending over WhatsApp, tracking RSVPs - lives behind the dashboard and is session-authenticated. Sign in at https://app.ueventi.com/login. There is no programmatic API for those flows yet.

## Use the API

Render an invitation card as a PNG. No auth header needed:

```
curl -s -X POST https://app.ueventi.com/api/tools/render-invitation \
  -H "Content-Type: application/json" \
  -d '{
    "style": "elegant",
    "language": "en",
    "eventType": "wedding",
    "eventName": "Maya & Daniel",
    "bodyText": "We would be delighted to have you celebrate with us.",
    "eventDate": "2026-09-12",
    "venueName": "The Old Vineyard, Napa"
  }' \
  --output invitation.png
```

A successful call returns `200` with an `image/png` body. The full request schema and enum values are in the OpenAPI spec at https://ueventi.com/openapi.json.

## Errors

Every error is a JSON object shaped `{ "error": "..." }`, never an HTML page.

| Status | Meaning | What to do |
| --- | --- | --- |
| 400 | Validation failed - a field was too long, the date could not be parsed, an enum value was not recognized, or neither eventName nor title was provided. | Fix the request body and retry. |
| 429 | Rate limit exceeded - more than 30 requests in the last hour from your IP. | Wait for the hour window to reset, then retry. Slow down concurrent calls. |
| 500 | The card could not be generated. | Retry once; if it persists, contact support. |

## Coming later

Self-serve API keys for the authenticated surface (guest lists, sending, RSVP data) are planned but not available yet. Want early access? Email support@ueventi.com and tell us what you are building.

## Revocation

Not applicable today - the public endpoints use no credentials, so there is nothing to revoke. This section will describe key rotation and revocation once self-serve API keys ship.