From 5e90037f1a495c74d2e67e895447516562fdef04 Mon Sep 17 00:00:00 2001 From: Daniel Chung Date: Thu, 7 Jan 2021 12:14:52 -0500 Subject: [PATCH] api.md: clarify response behaviour for ACL POST endpoint Signed-off-by: Daniel Chung --- api.md | 39 +++++++++++++++++++++++++++++++++------ 1 file changed, 33 insertions(+), 6 deletions(-) diff --git a/api.md b/api.md index c14049691..ccd539027 100644 --- a/api.md +++ b/api.md @@ -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" + ] + } + ] +} +``` + #### `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"} ```