# Work References

> Portable, verified employment references anchored to company domains via DNS.

## What Is Work References?

Work References is a UK-based platform that lets employers issue tamper-proof employment references. Each reference is cryptographically signed using Ed25519 and verified via a DNS TXT record on the employer's domain. Anyone can verify a reference instantly — no account required.

## Key Concepts

- **Gold Verification**: Signature valid AND DNS TXT record found on the issuer's domain.
- **Silver Verification**: Signature valid but DNS record not found (domain may have changed hands).
- **Invalid**: Signature does not match — reference has been tampered with.
- **Ed25519**: The digital signature algorithm used (via TweetNaCl.js).
- **DNS Anchoring**: Public keys are published as TXT records at `REF1._workreferences.<domain>`.
- **Zero-Knowledge**: Private keys are encrypted client-side with the user's password. The server never sees unencrypted keys.

## Verification Levels

| Level   | Signature | DNS Record | Meaning                                  |
|---------|-----------|------------|------------------------------------------|
| Gold    | Valid     | Found      | Authentic reference from verified domain  |
| Silver  | Valid     | Not found  | Signature checks out but domain not live  |
| Invalid | Failed    | N/A        | Reference has been altered                |

## API Endpoints

All endpoints are at `https://www.workreferences.org`.

### Public (No Auth)
- `GET /api/verify/{id}` — Verify a reference by UUID
- `POST /api/verify/{id}` — Verify + check uploaded PDF hash
- `POST /api/tenants/lookup` — Check if a domain is registered
- `GET /api/dns/check?domain=example.com` — Check DNS TXT record status
- `GET /api/health` — Health check

### Authenticated (Per-Tenant API Key)
- `POST /api/partners/references` — Create a signed reference
  - Header: `x-api-key: rp_...` or `Authorization: Bearer rp_...`
  - Body: `{ candidateName, role, dates, text, signingPassword }`

### Authenticated (Global Partner Key)
- `POST /api/partners/references` — Same endpoint, backward compatible
  - Header: `x-partner-key: <key>` or `Authorization: Bearer <key>`
  - Body: `{ tenantDomain, candidateName, role, dates, text, signingPassword }`

## DNS Record Format

```
Host:  REF1._workreferences.example.com
Type:  TXT
Value: v=workreferences1; k=ed25519; p=<base64-public-key>
```

## Links

- Website: https://www.workreferences.org
- OpenAPI Spec: https://www.workreferences.org/openapi.json
- Full Documentation: https://www.workreferences.org/llms-full.txt
- Developer Docs: https://www.workreferences.org/implement
- API Reference: https://www.workreferences.org/implement/api-reference
- Open Standard: https://www.workreferences.org/standard
- DNS Setup Guide: https://www.workreferences.org/dns-guide
- Live Demo: https://www.workreferences.org/demo