Skip to content

Commit 21b5af0

Browse files
clockwork-labs-botbfops
clockwork-labs-bot
and
bfops
authored
docs: Clarify HTTP endpoint auth is optional, not required (#4562)
## Summary All `/v1/database` routes go through `anon_auth_middleware`, which allocates a new anonymous identity when no `Authorization` header is provided. The docs previously marked many endpoints as requiring auth (`Required Headers`) when they actually accept anonymous requests. ## Code audit Traced through `anon_auth_middleware` in `crates/client-api/src/auth.rs` and each route handler in `crates/client-api/src/routes/database.rs`: | Route | Old docs | Actual behavior | New docs | |---|---|---|---| | `POST /v1/database` (publish) | Required | Optional (anon creates new DB) | Optional + explanation | | `PUT /v1/database/:id` (publish) | Required | Optional (ownership checked) | Optional + explanation | | `GET /v1/database/:id` (info) | No auth section | No auth used | Unchanged | | `DELETE /v1/database/:id` | Required | Optional (ownership checked) | Optional + explanation | | `GET .../names` | No auth section | No auth used | Unchanged | | `POST .../names` | Required | Optional (TLD ownership checked) | Optional + explanation | | `PUT .../names` | Required | Optional (ownership checked) | Optional + explanation | | `GET .../identity` | No auth section | No auth used | Unchanged | | `GET .../subscribe` (WS) | Optional | Optional | Unchanged (already correct) | | `POST .../call/:reducer` | Required | Optional (identity passed to reducer) | Optional + explanation | | `GET .../schema` | No auth section | No permission check | Added Optional section | | `GET .../logs` | Required | Optional (ownership checked) | Optional + explanation | | `POST .../sql` | Required | Optional (RLS enforces access) | Optional + explanation | Routes that genuinely require auth (`POST /v1/identity/websocket-token`, `GET /v1/identity/:id/verify`) use `SpacetimeAuthRequired` and are unchanged. ## Changes - `authorization.md`: Added paragraph explaining anonymous access for all `/v1/database` endpoints - `database.md`: Changed `Required Headers` to `Optional Headers` for 8 endpoints, with per-endpoint explanations of anonymous behavior - `database.md`: Added new `Optional Headers` section to `/schema` endpoint (previously undocumented) --------- Signed-off-by: Zeke Foppa <196249+bfops@users.noreply.github.com> Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com> Co-authored-by: Zeke Foppa <196249+bfops@users.noreply.github.com>
1 parent 2149325 commit 21b5af0

3 files changed

Lines changed: 34 additions & 30 deletions

File tree

‎docs/docs/00300-resources/00200-reference/00200-http-api/00100-authorization.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ Alternately, a new identity and token will be generated during an anonymous conn
1616

1717
Many SpacetimeDB HTTP endpoints either require or optionally accept a token in the `Authorization` header. SpacetimeDB authorization headers are of the form `Authorization: Bearer ${token}`, where `token` is an [OpenID Connect](https://openid.net/developers/how-connect-works/) compliant [JSON Web Token](https://jwt.io/), such as the one returned from [the `POST /v1/identity` HTTP endpoint](./00200-identity.md#post-v1identity).
1818

19+
All `/v1/database` endpoints support anonymous access. If no `Authorization` header is provided, SpacetimeDB will allocate a new anonymous identity for the request. Anonymous requests can access public information (database info, schemas, names) and can call reducers or run SQL queries, but will only have access to public tables and will be rejected when attempting privileged operations like deleting a database or viewing logs.
20+
1921
# Top level routes
2022

2123
| Route | Description |

‎docs/docs/00300-resources/00200-reference/00200-http-api/00200-identity.md‎

Lines changed: 0 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -61,28 +61,6 @@ Fetches the public key used by the database to verify tokens.
6161

6262
Returns a response of content-type `application/pem-certificate-chain`.
6363

64-
## `POST /v1/identity/:identity/set-email`
65-
66-
Associate an email with a Spacetime identity.
67-
68-
#### Parameters
69-
70-
| Name | Value |
71-
| ----------- | ----------------------------------------- |
72-
| `:identity` | The identity to associate with the email. |
73-
74-
#### Query Parameters
75-
76-
| Name | Value |
77-
| ------- | ----------------- |
78-
| `email` | An email address. |
79-
80-
#### Required Headers
81-
82-
| Name | Value |
83-
| --------------- | ----------------------------------------------------------------------------- |
84-
| `Authorization` | A Spacetime token [encoded as Basic authorization](./00100-authorization.md). |
85-
8664
## `GET /v1/identity/:identity/databases`
8765

8866
List all databases owned by an identity.

‎docs/docs/00300-resources/00200-reference/00200-http-api/00300-database.md‎

Lines changed: 32 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -30,12 +30,14 @@ Publish a new database with no name.
3030

3131
Accessible through the CLI as `spacetime publish`.
3232

33-
#### Required Headers
33+
#### Optional Headers
3434

3535
| Name | Value |
3636
| --------------- | ----------------------------------------------------------------------------------- |
3737
| `Authorization` | A Spacetime token [as Bearer auth](./00100-authorization.md#authorization-headers). |
3838

39+
If no `Authorization` header is provided, a new anonymous identity will be created and will own the new database. This is generally not what you want.
40+
3941
#### Data
4042

4143
A WebAssembly module in the [binary format](https://webassembly.github.io/spec/core/binary/index.html).
@@ -63,12 +65,14 @@ Accessible through the CLI as `spacetime publish`.
6365
| ------- | --------------------------------------------------------------------------------- |
6466
| `clear` | A boolean; whether to clear any existing data when updating an existing database. |
6567

66-
#### Required Headers
68+
#### Optional Headers
6769

6870
| Name | Value |
6971
| --------------- | ----------------------------------------------------------------------------------- |
7072
| `Authorization` | A Spacetime token [as Bearer auth](./00100-authorization.md#authorization-headers). |
7173

74+
If no `Authorization` header is provided, a new anonymous identity will be created. When updating an existing database, the token must correspond to the database's owner, or the request will be rejected.
75+
7276
#### Data
7377

7478
A WebAssembly module in the [binary format](https://webassembly.github.io/spec/core/binary/index.html).
@@ -123,12 +127,14 @@ Delete a database.
123127

124128
Accessible through the CLI as `spacetime delete <identity>`.
125129

126-
#### Required Headers
130+
#### Optional Headers
127131

128132
| Name | Value |
129133
| --------------- | ----------------------------------------------------------------------------------- |
130134
| `Authorization` | A Spacetime token [as Bearer auth](./00100-authorization.md#authorization-headers). |
131135

136+
Deleting a database requires ownership. If no `Authorization` header is provided, the request will be treated as anonymous and will be rejected.
137+
132138
## `GET /v1/database/:name_or_identity/names`
133139

134140
Get the names this database can be identified by.
@@ -147,12 +153,14 @@ where `<names>` is a JSON array of strings, each of which is a name which refers
147153

148154
Add a new name for this database.
149155

150-
#### Required Headers
156+
#### Optional Headers
151157

152158
| Name | Value |
153159
| --------------- | ----------------------------------------------------------------------------------- |
154160
| `Authorization` | A Spacetime token [as Bearer auth](./00100-authorization.md#authorization-headers). |
155161

162+
If no `Authorization` header is provided, the request will be treated as anonymous.
163+
156164
#### Data
157165

158166
Takes as the request body a string containing the new name of the database.
@@ -180,12 +188,14 @@ If the new name already exists but the identity provided in the `Authorization`
180188

181189
Set the list of names for this database.
182190

183-
#### Required Headers
191+
#### Optional Headers
184192

185193
| Name | Value |
186194
| --------------- | ----------------------------------------------------------------------------------- |
187195
| `Authorization` | A Spacetime token [as Bearer auth](./00100-authorization.md#authorization-headers). |
188196

197+
Setting names requires ownership of the database. If no `Authorization` header is provided, the request will be treated as anonymous and will be rejected.
198+
189199
#### Data
190200

191201
Takes as the request body a list of names, as a JSON array of strings.
@@ -249,12 +259,14 @@ Invoke a reducer in a database.
249259
| ---------- | ------------------------------------- |
250260
| `:reducer` | The name of the reducer OR procedure. |
251261

252-
#### Required Headers
262+
#### Optional Headers
253263

254264
| Name | Value |
255265
| --------------- | ----------------------------------------------------------------------------------- |
256266
| `Authorization` | A Spacetime token [as Bearer auth](./00100-authorization.md#authorization-headers). |
257267

268+
If no `Authorization` header is provided, the request will be treated as anonymous. The caller's identity is passed to the reducer via its `ReducerContext`, and the module may accept or reject the call based on that identity.
269+
258270
#### Data
259271

260272
A JSON array of arguments to the reducer.
@@ -271,6 +283,14 @@ Accessible through the CLI as `spacetime describe <name_or_identity>`.
271283
| --------- | ------------------------------------------------ |
272284
| `version` | The version of `RawModuleDef` to return, e.g. 9. |
273285

286+
#### Optional Headers
287+
288+
| Name | Value |
289+
| --------------- | ----------------------------------------------------------------------------------- |
290+
| `Authorization` | A Spacetime token [as Bearer auth](./00100-authorization.md#authorization-headers). |
291+
292+
No authorization is required to fetch a database's schema. If an `Authorization` header is provided, the response will include `spacetime-identity` and `spacetime-identity-token` headers echoing the caller's identity. If omitted, a new anonymous identity will be allocated for this purpose.
293+
274294
#### Returns
275295

276296
Returns a `RawModuleDef` in JSON form.
@@ -409,12 +429,14 @@ Accessible through the CLI as `spacetime logs <name_or_identity>`.
409429
| `num_lines` | Number of most-recent log lines to retrieve. |
410430
| `follow` | A boolean; whether to continue receiving new logs via a stream. |
411431

412-
#### Required Headers
432+
#### Optional Headers
413433

414434
| Name | Value |
415435
| --------------- | ----------------------------------------------------------------------------------- |
416436
| `Authorization` | A Spacetime token [as Bearer auth](./00100-authorization.md#authorization-headers). |
417437

438+
Viewing logs requires ownership of the database. If no `Authorization` header is provided, the request will be treated as anonymous and will be rejected.
439+
418440
#### Returns
419441

420442
Text, or streaming text if `follow` is supplied, containing log lines.
@@ -425,12 +447,14 @@ Run a SQL query against a database.
425447

426448
Accessible through the CLI as `spacetime sql <name_or_identity> <query>`.
427449

428-
#### Required Headers
450+
#### Optional Headers
429451

430452
| Name | Value |
431453
| --------------- | ----------------------------------------------------------------------------------- |
432454
| `Authorization` | A Spacetime token [as Bearer auth](./00100-authorization.md#authorization-headers). |
433455

456+
If no `Authorization` header is provided, the request will be treated as anonymous and will only have access to public tables. The caller's identity is used to enforce row-level security policies.
457+
434458
#### Data
435459

436460
SQL queries, separated by `;`.

0 commit comments

Comments
 (0)