api.md: clarify response behaviour for ACL POST endpoint
@@ -367,10 +367,11 @@ Etag: "e0b2816b418b3f266309d94426ac7668ab3c1fa87798785bf82f1085cc2f6d9c"
#### `POST /api/v2/tailnet/:tailnet/acl` - set ACL for a tailnet
-Sets the ACL for the given tailnet. HuJSON and JSON are both accepted inputs. An `If-Match` header can be set to avoid missed updates.
+Sets the ACL for the given domain.
+HuJSON and JSON are both accepted inputs.
+An `If-Match` header can be set to avoid missed updates.
-Returns error for invalid ACLs.
-Returns error if using an `If-Match` header and the ETag does not match.
+Returns the updated ACL in JSON or HuJSON according to the `Accept` header on success. Otherwise, errors are returned for incorrectly defined ACLs, ACLs with failing tests on attempted updates, and mismatched `If-Match` header and ETag.
##### Parameters
@@ -380,7 +381,17 @@ Returns error if using an `If-Match` header and the ETag does not match.
`Accept` - Sets the return type of the updated ACL. Response is parsed `JSON` if `application/json` is explicitly named, otherwise HuJSON will be returned.
###### POST Body
-ACL JSON or HuJSON (see https://tailscale.com/kb/1018/acls)
+
+The POST body should be a JSON or [HuJSON](https://github.com/tailscale/hujson#hujson---human-json) formatted JSON object.
+An ACL policy may contain the following top-level properties:
+
+* `Groups` - Static groups of users which can be used for ACL rules.
+* `Hosts` - Hostname aliases to use in place of IP addresses or subnets.
+* `ACLs` - Access control lists.
+* `TagOwners` - Defines who is allowed to use which tags.
+* `Tests` - Run on ACL updates to check correct functionality of defined ACLs.
+
+See https://tailscale.com/kb/1018/acls for more information on those properties.
##### Example
```
@@ -411,7 +422,7 @@ curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl' \
}'
```
-Response
+Response:
```
// Example/default ACLs for unrestricted connections.
{
@@ -436,9 +447,25 @@ Response
}
```
+Failed test error response:
+```
+{
+ "message": "test(s) failed",
+ "data": [
+ {
+ "user": "user1@example.com",
+ "errors": [
+ "address \"user2@example.com:400\": want: Accept, got: Drop"
+ ]
+ }
+ ]
+}
+```
+
<a name=tailnet-acl-preview-post></a>
#### `POST /api/v2/tailnet/:tailnet/acl/preview` - preview rule matches on an ACL for a resource
+
Determines what rules match for a user on an ACL without saving the ACL to the server.
##### Parameters
@@ -477,7 +504,7 @@ curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl?user=user1@exampl
}'
```
-Response
+Response:
```
{"matches":[{"users":["*"],"ports":["*:*"],"lineNumber":19}],"user":"user1@example.com"}
```
