diff --git a/website/source/docs/agent/http/acl.html.markdown b/website/source/docs/agent/http/acl.html.markdown index 6e7186c223..b3b50abbba 100644 --- a/website/source/docs/agent/http/acl.html.markdown +++ b/website/source/docs/agent/http/acl.html.markdown @@ -3,16 +3,16 @@ layout: "docs" page_title: "ACLs (HTTP)" sidebar_current: "docs-agent-http-acl" description: > - The ACL endpoints are used to create, update, destroy and query ACL tokens. + The ACL endpoints are used to create, update, destroy, and query ACL tokens. --- # ACL HTTP Endpoint -The ACL endpoints are used to create, update, destroy and query ACL tokens. +The ACL endpoints are used to create, update, destroy, and query ACL tokens. The following endpoints are supported: -* [`/v1/acl/create`](#acl_create): Creates a new token with policy -* [`/v1/acl/update`](#acl_update): Update the policy of a token +* [`/v1/acl/create`](#acl_create): Creates a new token with a given policy +* [`/v1/acl/update`](#acl_update): Updates the policy of a token * [`/v1/acl/destroy/`](#acl_destroy): Destroys a given token * [`/v1/acl/info/`](#acl_info): Queries the policy of a given token * [`/v1/acl/clone/`](#acl_clone): Creates a new token by cloning an existing token @@ -20,21 +20,27 @@ The following endpoints are supported: ### /v1/acl/create -The create endpoint is used to make a new token. A token has a name, -type, and a set of ACL rules. The name is opaque to Consul, and type -is either "client" or "management". A management token is effectively -like a root user, and has the ability to perform any action including -creating, modifying, and deleting ACLs. A client token can only perform -actions as permitted by the rules associated, and may never manage ACLs. -This means the request to this endpoint must be made with a management -token. +The `create` endpoint is used to make a new token. A token has a name, +a type, and a set of ACL rules. + +The `Name` property is opaque to Consul. To aid human operators, it should +be a meaningful indicator of the ACL's purpose. + +Type is either `client` or `management`. A management token is comparable +to a root user and has the ability to perform any action including +creating, modifying, and deleting ACLs. + +By constrast, a client token can only perform actions as permitted by the +rules associated. Client tokens can never manage ACLs. Given this limitation, +only a management token can be used to make requests to the `/v1/acl/create` +endpoint. In any Consul cluster, only a single datacenter is authoritative for ACLs, so all requests are automatically routed to that datacenter regardless -of the agent that the request is made to. +of the agent to which the request is made. -The create endpoint expects a JSON request body to be PUT. The request -body must look like: +The create endpoint supports a JSON request body with the PUT. The request +body may take the form: ```javascript { @@ -44,12 +50,13 @@ body must look like: } ``` -None of the fields are mandatory, and in fact no body needs to be PUT -if the defaults are to be used. The `Name` and `Rules` default to being -blank, and the `Type` defaults to "client". The format of `Rules` is -[documented here](/docs/internals/acl.html). +None of the fields are mandatory. In fact, no body needs to be PUT if the +defaults are to be used. The `Name` and `Rules` fields default to being +blank, and the `Type` defaults to "client". -The return code is 200 on success, along with a body like: +The format of the `Rules` property is [documented here](/docs/internals/acl.html). + +A successful response body will return the `ID` of the newly created ACL, like so: ```javascript { @@ -57,22 +64,20 @@ The return code is 200 on success, along with a body like: } ``` -This is used to provide the ID of the newly created ACL token. - ### /v1/acl/update -The update endpoint is used to modify the policy for a given -ACL token. It is very similar to the create endpoint, however -instead of generating a new token ID, the `ID` field must be -provided. Requests to this endpoint must be made with a management +The update endpoint is used to modify the policy for a given ACL token. It +is very similar to the create endpoint; however, instead of generating a new +token ID, the `ID` field must be provided. As with [`/v1/acl/create`](#acl_create), +requests to this endpoint must be made with a management token. In any Consul cluster, only a single datacenter is authoritative for ACLs, so all requests are automatically routed to that datacenter regardless -of the agent that the request is made to. +of the agent to which the request is made. -The update endpoint expects a JSON request body to be PUT. The request -body must look like: +The update endpoint requires a JSON request body to the PUT. The request +body may look like: ```javascript { @@ -83,26 +88,22 @@ body must look like: } ``` -Only the `ID` field is mandatory, the other fields provide defaults. -The `Name` and `Rules` default to being blank, and the `Type` defaults to "client". +Only the `ID` field is mandatory. The other fields provide defaults: the +`Name` and `Rules` fields default to being blank, and `Type` defaults to "client". The format of `Rules` is [documented here](/docs/internals/acl.html). -The return code is 200 on success. - ### /v1/acl/destroy/\ -The destroy endpoint is hit with a PUT and destroys the given ACL token. -The request is automatically routed to the authoritative ACL datacenter. -The token being destroyed must be provided after the slash, and requests -to the endpoint must be made with a management token. +The destroy endpoint must be hit with a PUT. This endpoint destroys the ACL +token identified by the `id` portion of the path. -The return code is 200 on success. +The request is automatically routed to the authoritative ACL datacenter. +Requests to this endpoint must be made with a management token. ### /v1/acl/info/\ -This endpoint is hit with a GET and returns the token information -by ID. All requests are routed to the authoritative ACL datacenter -The token being queried must be provided after the slash. +The info endpoint must be hit with a GET. This endpoint returns the ACL +token information identified by the `id` portion of the path. It returns a JSON body like this: @@ -119,17 +120,20 @@ It returns a JSON body like this: ] ``` -If the session is not found, null is returned instead of a JSON list. +If the ACL is not found, null is returned instead of a JSON list. ### /v1/acl/clone/\ -The clone endpoint is hit with a PUT and returns a token ID that -is cloned from an existing token. This allows a token to serve -as a template for others, making it simple to generate new tokens -without complex rule management. The source token must be provided -after the slash. Requests to this endpoint require a management token. +The clone endpoint must be hit with a PUT. It clones the ACL identified +by the `id` portion of the path and returns a new token `ID`. This allows +a token to serve as a template for others, making it simple to generate new +tokens without complex rule management. -The return code is 200 on success, along with a body like: +The request is automatically routed to the authoritative ACL datacenter. +Requests to this endpoint must be made with a management token. + +As with `create`, a successful response body will return the `ID` of the newly +created ACL, like so: ```javascript { @@ -137,12 +141,10 @@ The return code is 200 on success, along with a body like: } ``` -This is used to provide the ID of the newly created ACL token. - ### /v1/acl/list -The list endpoint is hit with a GET and lists all the active -ACL tokens. This is a privileged endpoint, and requires a +The list endpoint must be hit with a GET. It lists all the active +ACL tokens. This is a privileged endpoint and requires a management token. It returns a JSON body like this: