tenseleyflow/shithub / 74c24e2

Browse files

docs/changelog: document S50 §1 user emails + SSH keys REST surface

Authored by mfwolffe <wolffemf@dukes.jmu.edu>
SHA
74c24e2ee2699fb759f41d74bc7537e82f1f2cb9
Parents
a9f82bb
Tree
6f269a0

2 changed files

StatusFile+-
M CHANGELOG.md 11 0
M docs/public/api/users.md 136 0
CHANGELOG.mdmodified
@@ -24,6 +24,17 @@ between minor releases.
2424
 - **Pagination helper** `internal/web/handlers/api/apipage` —
2525
   emits canonical RFC 8288 Link headers (`first`/`prev`/`next`/`last`)
2626
   with absolute URLs rooted at the configured public base URL.
27
+- **REST: user emails (S50 §1).** `GET /api/v1/user/emails` lists
28
+  the authenticated user's emails. Optional `?verified=true|false`
29
+  filter. Scope: `user:read`.
30
+- **REST: user SSH keys (S50 §1).** `GET/POST /api/v1/user/keys`
31
+  and `GET/DELETE /api/v1/user/keys/{id}` expose CRUD for git
32
+  authentication keys. Signing keys are tracked separately by a
33
+  new `kind` column on `user_ssh_keys` and remain on the HTML
34
+  surface for now. Scopes: `user:read` for GETs, `user:write` for
35
+  mutations.
36
+- **Capabilities:** `user-emails`, `ssh-keys` added to
37
+  `/api/v1/meta` response.
2738
2839
 ### Changed
2940
docs/public/api/users.mdmodified
@@ -51,6 +51,142 @@ authenticating PAT.
5151
5252
 > **Planned.** `GET /api/v1/user/repos` is not shipped yet.
5353
54
+## Email addresses
55
+
56
+### List the authenticated user's emails
57
+
58
+```
59
+GET /api/v1/user/emails
60
+```
61
+
62
+Required scope: `user:read`.
63
+
64
+Returns every email address attached to the authenticating user.
65
+Use `?verified=true` (or `?verified=false`) to filter to a single
66
+verification state. Omit the query parameter to list both.
67
+
68
+#### Response
69
+
70
+```json
71
+[
72
+  {
73
+    "id": 7,
74
+    "email": "alice+primary@example.test",
75
+    "primary": true,
76
+    "verified": true
77
+  },
78
+  {
79
+    "id": 8,
80
+    "email": "alice+work@example.test",
81
+    "primary": false,
82
+    "verified": false
83
+  }
84
+]
85
+```
86
+
87
+| Field      | Type   | Notes                                             |
88
+|------------|--------|---------------------------------------------------|
89
+| `id`       | int64  | Stable per-row id.                                |
90
+| `email`    | string | The email address as stored.                      |
91
+| `primary`  | bool   | Marks the account's primary delivery address.     |
92
+| `verified` | bool   | `true` once a verification link has been clicked. |
93
+
94
+#### Errors
95
+
96
+| Status | When                                |
97
+|-------:|-------------------------------------|
98
+|    401 | PAT missing/invalid/expired/revoked. |
99
+|    403 | PAT lacks `user:read` scope.         |
100
+
101
+> **Planned.** `POST` and `DELETE /api/v1/user/emails` are not
102
+> shipped yet — use `/settings/account` in the web UI to add or
103
+> remove addresses for now.
104
+
105
+## SSH keys
106
+
107
+SSH authentication keys for git-over-SSH. Signing keys live at a
108
+separate `/user/ssh_signing_keys` surface (not yet shipped).
109
+
110
+### List SSH keys
111
+
112
+```
113
+GET /api/v1/user/keys
114
+```
115
+
116
+Required scope: `user:read`.
117
+
118
+Returns the authenticated user's authentication keys (signing
119
+keys are not returned here). Paginated via `?per_page=` and
120
+`?page=`; the response carries the standard `Link:` header.
121
+
122
+#### Response
123
+
124
+```json
125
+[
126
+  {
127
+    "id": 12,
128
+    "title": "laptop",
129
+    "key": "ssh-ed25519 AAAA…",
130
+    "fingerprint": "SHA256:abc…",
131
+    "key_type": "ssh-ed25519",
132
+    "verified": true,
133
+    "read_only": false,
134
+    "created_at": "2026-05-12T04:00:00Z"
135
+  }
136
+]
137
+```
138
+
139
+### Get a single SSH key
140
+
141
+```
142
+GET /api/v1/user/keys/{id}
143
+```
144
+
145
+Required scope: `user:read`.
146
+
147
+404 when the id does not belong to the authenticating user, or
148
+when it is a signing key (use the signing-key surface).
149
+
150
+### Add an SSH key
151
+
152
+```
153
+POST /api/v1/user/keys
154
+```
155
+
156
+Required scope: `user:write`.
157
+
158
+#### Request body
159
+
160
+```json
161
+{ "title": "laptop", "key": "ssh-ed25519 AAAA…" }
162
+```
163
+
164
+| Field   | Type   | Notes                                                                    |
165
+|---------|--------|--------------------------------------------------------------------------|
166
+| `title` | string | 1–80 characters; user-visible label.                                     |
167
+| `key`   | string | The contents of your `.pub` file (no leading comment, no trailing data). |
168
+
169
+Returns `201` on success with the same shape as the list endpoint.
170
+
171
+#### Errors
172
+
173
+| Status | When                                                                         |
174
+|-------:|------------------------------------------------------------------------------|
175
+|    401 | PAT missing/invalid.                                                         |
176
+|    403 | PAT lacks `user:write` scope.                                                |
177
+|    422 | Title invalid, blob unparseable, key already registered, or per-user cap hit. |
178
+
179
+### Delete an SSH key
180
+
181
+```
182
+DELETE /api/v1/user/keys/{id}
183
+```
184
+
185
+Required scope: `user:write`.
186
+
187
+Returns `204 No Content` on success, `404` when the id does not
188
+belong to the authenticating user.
189
+
54190
 ## Stars
55191
56192
 The starred-repos surface for the authenticating user.