Add meta.sr.ht user API documentation

1 files changed, 264 insertions, 1 deletions

diff --git a/meta.sr.ht/user-api.md b/meta.sr.ht/user-api.md
index 5606b4b..0c154e2 100644
--- a/meta.sr.ht/user-api.md
+++ b/meta.sr.ht/user-api.md
@@ -1,3 +1,266 @@
 # meta.sr.ht user API
 
-TODO: write this doc
+The meta.sr.ht API allows you to view and edit user information on meta.sr.ht
+programmatically. This API follows the [standard sourcehut API
+conventions](../api-conventions.md).
+
+## Authentication
+
+Authentication is done via the [meta.sr.ht OAuth
+flow](oauth-api.md). The following OAuth scopes are available for meta.sr.ht:
+
+- **audit:read**: read the security audit log
+- **keys:read**, **keys:write**: read & update user SSH & PGP keys
+- **profile:read**, **profile:write**: read & update profile information
+
+## Resources
+
+### User resource
+
+meta.sr.ht expands on the [standard user
+resource](../api-conventions.md#user-resource).
+
+```json
+{
+  "canonical_name": "~username",
+  "name": "username",
+  "email": "email",
+  "url": "url" or null,
+  "location": "location" or null,
+  "bio": "bio" or null,
+  "use_pgp_key": pgp key resource ID
+}
+```
+
+- **use_pgp_key** is the ID of the user's preferred PGP key, which can be found
+  via [`GET /api/user/pgp-keys/:id`](#get-apiuserpgpkeysid).
+
+### Audit log entry resource
+
+```json
+{
+  "id": integer,
+  "ip": "IP address",
+  "action": "event type",
+  "details": "event details",
+  "created": "timestamp"
+}
+```
+
+### SSH key resource
+
+```json
+{
+  "id": integer,
+  "authorized": "timestamp",
+  "comment": "SSH key comment",
+  "fingerprint": "SSH key fingerprint",
+  "key": "SSH key (authorized_keys format)",
+  "owner": short-form user resource,
+  "last_used": "timestamp"
+}
+```
+
+- **last_used** is omitted when viewing an SSH key which is not owned by the
+  authorized user.
+
+### PGP key resource
+
+```json
+{
+  "id": integer,
+  "key": "armored PGP key",
+  "key_id": "PGP key fingerprint",
+  "email": "First email found in the PGP key",
+  "authorized": "timestamp",
+  "owner": short-form user resource
+}
+```
+
+## Endpoints
+
+### GET /api/user/profile
+
+**OAuth scope**: `profile:read`
+
+Returns the authenticated user's [user resource](#user-resource).
+
+### PUT /api/user/profile
+
+**OAuth scope**: `profile:update`
+
+Updates the authenticated user's profile.
+
+**Request body**
+
+```json
+{
+  "url": "url" or null, (optional)
+  "location": "location" or null, (optional)
+  "bio": "bio" or null, (optional)
+  "email": "email" (optional)
+}
+```
+
+**Response**
+
+Updated [user resource](#user-resource).
+
+**Notes**
+
+- When updating **email**, the returned user resource will not reflect the
+  update. The user must click the confirmation link which is sent to their new
+  email address before the update will take effect.
+
+### GET /api/user/audit-log
+
+**OAuth scope**: `audit-log:read`
+
+List of [audit log entry resources](#audit-log-entry-resource).
+
+### GET /api/user/ssh-keys
+
+**OAuth scope**: `keys:read`
+
+List of [SSH key resources](#ssh-key-resource).
+
+### POST /api/user/ssh-keys
+
+**OAuth scope**: `keys:write`
+
+Creates a new [SSH key resource](#ssh-key-resource).
+
+**Request body**
+
+```json
+{
+  "ssh-key": "SSH key (authorized_keys format)"
+}
+```
+
+**Response**
+
+The new [SSH key resource](#ssh-key-resource).
+
+### GET /api/user/ssh-keys/:id
+
+**OAuth scope**: `keys:read`
+
+Retrieves an [SSH key resource](#ssh-key-resource). 
+
+### PUT /api/user/ssh-keys/:id
+
+**OAuth scope**: `keys:write`
+
+Updates the "last_used" time of this SSH key resource.
+
+**Response**
+
+The updated [SSH key resource](#ssh-key-resource).
+
+### DELETE /api/user/ssh-keys/:id
+
+**OAuth scope**: `keys:write`
+
+Deletes this SSH key resource.
+
+### GET /api/user/pgp-keys
+
+**OAuth scope**: `keys:read`
+
+List of [PGP key resources](#pgp-key-resource).
+
+### POST /api/user/pgp-keys
+
+**OAuth scope**: `keys:write`
+
+Creates a new [PGP key resource](#pgp-key-resource).
+
+**Request body**
+
+```json
+{
+  "pgp-key": "armored PGP key"
+}
+```
+
+**Response**
+
+The new [PGP key resource](#pgp-key-resource).
+
+### GET /api/user/pgp-keys/:id
+
+**OAuth scope**: `keys:read`
+
+Retrieves a [PGP key resource](#pgp-key-resource).
+
+### DELETE /api/user/pgp-keys/:id
+
+**OAuth scope**: `keys:write`
+
+Deletes this PGP key resource.
+
+## Webhooks
+
+### /api/user/...
+
+Webhook for user events. Includes the [standard webhook
+endpoints](../api-conventions.md#webhooks)
+
+#### profile:update
+
+**OAuth scope**: `profile:read`
+
+Issued when the user's profile (bio, email, etc) is updated.
+
+**Request body**
+
+The updated [user resource](#user-resource).
+
+#### ssh-key:add
+
+**OAuth scope**: `keys:read`
+
+Issued when the user adds an SSH key to their account.
+
+**Request body**
+
+The new [SSH key resource](#ssh-key-resource).
+
+#### ssh-key:remove
+
+**OAuth scope**: `keys:read`
+
+Issued when the user removes an SSH key from their account.
+
+**Request body**
+
+```json
+{
+  "id": integer ID of the affected SSH key resource
+}
+```
+
+#### pgp-key:add
+
+**OAuth scope**: `keys:read`
+
+Issued when the user adds a PGP key to their account.
+
+**Request body**
+
+The new [PGP key resource](#pgp-key-resource).
+
+#### pgp-key:remove
+
+**OAuth scope**: `keys:read`
+
+Issued when the user removes a PGP key from their account.
+
+**Request body**
+
+```json
+{
+  "id": integer ID of the affected PGP key resource
+}
+```