elastic · legrego · Oct 1, 2018 · Mar 26, 2018 · Apr 17, 2018 · Apr 17, 2018
diff --git a/docs/api.asciidoc b/docs/api.asciidoc
@@ -26,14 +26,15 @@ entirely.
 
 [float]
 == APIs
-
+* <<spaces-api>>
 * <<role-management-api>>
 * <<saved-objects-api>>
 * <<dashboard-import-api>>
 * <<logstash-configuration-management-api>>
 * <<url-shortening-api>>
 --
 
+include::api/spaces-management.asciidoc[]
 include::api/role-management.asciidoc[]
 include::api/saved-objects.asciidoc[]
 include::api/dashboard-import.asciidoc[]

diff --git a/docs/api/role-management/put.asciidoc b/docs/api/role-management/put.asciidoc
@@ -30,7 +30,7 @@ that begin with `_` are reserved for system usage.
 `elasticsearch`:: (object) Optional {es} cluster and index privileges, valid keys are 
 `cluster`, `indices` and `run_as`. For more information, see {xpack-ref}/defining-roles.html[Defining Roles].
 
-`kibana`:: (list) A list of objects that specify the <<kibana-privileges>>.
+`kibana`:: (object) An object that specifies the <<kibana-privileges>>. Valid keys are `global` and `space`. Privileges defined in the `global` key will apply to all spaces within Kibana, and will take precedent over any privileges defined in the `space` key. For example, specifying `global: ["all"]` will grant full access to all spaces within Kibana, even if the role indicates that a specific space should only have `read` privileges. 
 
 ===== Example
 
@@ -52,13 +52,47 @@ PUT /api/security/role/my_kibana_role
       "query" : "{\"match\": {\"title\": \"foo\"}}"
     } ],
   },
-  "kibana": [ {
-      "privileges": [ "all" ]
-  } ],
+  "kibana": {
+    "global": ["all"]
+  }
 }
 --------------------------------------------------
 // KIBANA
 
 ==== Response
 
 A successful call returns a response code of `204` and no response body.
+
+
+==== Granting access to specific spaces
+To grant access to individual spaces within {kib}, specify the space identifier within the `kibana` object.
+
+Note: granting access 
+
+[source,js]
+--------------------------------------------------
+PUT /api/security/role/my_kibana_role
+{
+  "metadata" : {
+    "version" : 1
+  },
+  "elasticsearch": {
+    "cluster" : [ "all" ],
+    "indices" : [ {
+      "names" : [ "index1", "index2" ],
+      "privileges" : [ "all" ],
+      "field_security" : {
+        "grant" : [ "title", "body" ]
+      },
+      "query" : "{\"match\": {\"title\": \"foo\"}}"
+    } ],
+  },
+  "kibana": {
+    "global": [],
+    "space": {
+      "marketing": ["all"],
+      "engineering": ["read"] 
+    }
+  }
+}
+--------------------------------------------------
diff --git a/docs/api/spaces-management.asciidoc b/docs/api/spaces-management.asciidoc
@@ -0,0 +1,17 @@
+[role="xpack"]
+[[spaces-api]]
+== Kibana Spaces API
+
+experimental[This API is *experimental* and may be changed or removed completely in a future release. The underlying Spaces concepts are stable, but the APIs for managing Spaces are currently experimental.]
+
+The spaces API allows people to manage their spaces within {kib}.
+
+* <<spaces-api-post>>
+* <<spaces-api-put>>
+* <<spaces-api-get>>
+* <<spaces-api-delete>>
+
+include::spaces-management/post.asciidoc[]
+include::spaces-management/put.asciidoc[]
+include::spaces-management/get.asciidoc[]
+include::spaces-management/delete.asciidoc[]
diff --git a/docs/api/spaces-management/delete.asciidoc b/docs/api/spaces-management/delete.asciidoc
@@ -0,0 +1,25 @@
+[[spaces-api-delete]]
+=== Delete space
+
+experimental[This API is *experimental* and may be changed or removed completely in a future release. The underlying Spaces concepts are stable, but the APIs for managing Spaces are currently experimental.]
+
+[WARNING]
+==================================================
+Deleting a space will automatically delete all saved objects that belong to that space. This operation cannot be undone!
+==================================================
+
+==== Request
+
+To delete a space, submit a DELETE request to the `/api/spaces/space/<space_id>`
+endpoint:
+
+[source,js]
+--------------------------------------------------
+DELETE /api/spaces/space/marketing
+--------------------------------------------------
+// KIBANA
+
+==== Response
+
+If the space is successfully deleted, the response code is `204`; otherwise, the response
+code is 404.
diff --git a/docs/api/spaces-management/get.asciidoc b/docs/api/spaces-management/get.asciidoc
@@ -0,0 +1,77 @@
+[[spaces-api-get]]
+=== Get Space
+
+experimental[This API is *experimental* and may be changed or removed completely in a future release. The underlying Spaces concepts are stable, but the APIs for managing Spaces are currently experimental.]
+
+Retrieves all {kib} spaces, or a specific space.
+
+==== Get all {kib} spaces
+
+===== Request
+
+To retrieve all spaces, issue a GET request to the
+/api/spaces/space endpoint.
+
+[source,js]
+--------------------------------------------------
+GET /api/spaces/space
+--------------------------------------------------
+// KIBANA
+
+===== Response
+
+A successful call returns a response code of `200` and a response body containing a JSON 
+representation of the spaces.
+
+[source,js]
+--------------------------------------------------
+[
+  {
+    "id": "default",
+    "name": "Default",
+    "description" : "This is the Default Space",
+    "_reserved": true
+  },
+  {
+    "id": "marketing",
+    "name": "Marketing",
+    "description" : "This is the Marketing Space",
+    "color": "#aabbcc",
+    "initials": "MK"
+  },
+  {
+    "id": "sales",
+    "name": "Sales",
+    "initials": "MK"
+  },
+]
+--------------------------------------------------
+
+==== Get a specific space
+
+===== Request
+
+To retrieve a specific space, issue a GET request to
+the `/api/spaces/space/<space_id>` endpoint:
+
+[source,js]
+--------------------------------------------------
+GET /api/spaces/space/marketing
+--------------------------------------------------
+// KIBANA
+
+===== Response
+
+A successful call returns a response code of `200` and a response body containing a JSON 
+representation of the space.
+
+[source,js]
+--------------------------------------------------
+{
+  "id": "marketing",
+  "name": "Marketing",
+  "description" : "This is the Marketing Space",
+  "color": "#aabbcc",
+  "initials": "MK"
+}
+--------------------------------------------------
diff --git a/docs/api/spaces-management/post.asciidoc b/docs/api/spaces-management/post.asciidoc
@@ -0,0 +1,50 @@
+[[spaces-api-post]]
+=== Create Space
+
+experimental[This API is *experimental* and may be changed or removed completely in a future release. The underlying Spaces concepts are stable, but the APIs for managing Spaces are currently experimental.]
+
+Creates a new {kib} space. To update an existing space, use the PUT command.
+
+==== Request
+
+To create a space, issue a POST request to the 
+`/api/spaces/space` endpoint.
+
+[source,js]
+--------------------------------------------------
+POST /api/spaces/space
+--------------------------------------------------
+
+==== Request Body
+
+The following parameters can be specified in the body of a POST request to create a space:
+
+`id`:: (string) Required identifier for the space. This identifier becomes part of Kibana's URL when inside the space. This cannot be changed by the update operation.
+
+`name`:: (string) Required display name for the space.
+
+`description`:: (string) Optional description for the space.
+
+`initials`:: (string) Optionally specify the initials shown in the Space Avatar for this space. By default, the initials will be automatically generated from the space name.
+If specified, initials should be either 1 or 2 characters.
+
+`color`:: (string) Optioanlly specify the hex color code used in the Space Avatar for this space. By default, the color will be automatically generated from the space name.
+
+===== Example
+
+[source,js]
+--------------------------------------------------
+POST /api/spaces/space
+{
+  "id": "marketing",
+  "name": "Marketing",
+  "description" : "This is the Marketing Space",
+  "color": "#aabbcc",
+  "initials": "MK"
+}
+--------------------------------------------------
+// KIBANA
+
+==== Response
+
+A successful call returns a response code of `200` with the created Space.
diff --git a/docs/api/spaces-management/put.asciidoc b/docs/api/spaces-management/put.asciidoc
@@ -0,0 +1,50 @@
+[[spaces-api-put]]
+=== Update Space
+
+experimental[This API is *experimental* and may be changed or removed completely in a future release. The underlying Spaces concepts are stable, but the APIs for managing Spaces are currently experimental.]
+
+Updates an existing {kib} space. To create a new space, use the POST command.
+
+==== Request
+
+To update a space, issue a PUT request to the 
+`/api/spaces/space/<space_id>` endpoint.
+
+[source,js]
+--------------------------------------------------
+PUT /api/spaces/space/<space_id>
+--------------------------------------------------
+
+==== Request Body
+
+The following parameters can be specified in the body of a PUT request to update a space:
+
+`id`:: (string) Required identifier for the space. This identifier becomes part of Kibana's URL when inside the space. This cannot be changed by the update operation.
+
+`name`:: (string) Required display name for the space.
+
+`description`:: (string) Optional description for the space.
+
+`initials`:: (string) Optionally specify the initials shown in the Space Avatar for this space. By default, the initials will be automatically generated from the space name.
+If specified, initials should be either 1 or 2 characters.
+
+`color`:: (string) Optioanlly specify the hex color code used in the Space Avatar for this space. By default, the color will be automatically generated from the space name.
+
+===== Example
+
+[source,js]
+--------------------------------------------------
+PUT /api/spaces/space/marketing
+{
+  "id": "marketing",
+  "name": "Marketing",
+  "description" : "This is the Marketing Space",
+  "color": "#aabbcc",
+  "initials": "MK"
+}
+--------------------------------------------------
+// KIBANA
+
+==== Response
+
+A successful call returns a response code of `200` with the updated Space.
diff --git a/docs/development/core/development-basepath.asciidoc b/docs/development/core/development-basepath.asciidoc
@@ -48,15 +48,15 @@ $http.get(chrome.addBasePath('/api/plugin/things'));
 [float]
 ==== Server side
 
-Append `config.get('server.basePath')` to any absolute URL path.
+Append `request.getBasePath()` to any absolute URL path.
 
 ["source","shell"]
 -----------
 const basePath = server.config().get('server.basePath');
 server.route({
   path: '/redirect',
-  handler(req, reply) {
-    reply.redirect(`${basePath}/otherLocation`);
+  handler(request, reply) {
+    reply.redirect(`${request.getBasePath()}/otherLocation`);
   }
 });
 -----------

diff --git a/docs/index.asciidoc b/docs/index.asciidoc
@@ -52,6 +52,8 @@ include::monitoring/index.asciidoc[]
 
 include::management.asciidoc[]
 
+include::spaces/index.asciidoc[]
+
 include::security/index.asciidoc[]
 
 include::management/watcher-ui/index.asciidoc[]

diff --git a/docs/security/authorization/index.asciidoc b/docs/security/authorization/index.asciidoc
@@ -2,10 +2,13 @@
 [[xpack-security-authorization]]
 === Authorization
 
-Authorizing users to use {kib} in most configurations is as simple as assigning the user
+Authorizing users to use {kib} in simple configurations is as easy as assigning the user
 either the `kibana_user` or `kibana_dashboard_only_user` reserved role. If you're running 
-a single tenant of {kib} against your {es} cluster, this is sufficient and no other 
-action is required.
+a single tenant of {kib} against your {es} cluster, and you're not controlling access to individual spaces, then this is sufficient and no other action is required.
+
+==== Spaces
+
+If you want to control individual spaces in {kib}, do **not** use the `kibana_user` or `kibana_dashboard_only_user` roles. Users with these roles are able to access all spaces in Kibana. Instead, create your own roles that grant access to specific spaces.
 
 ==== Multi-tenant {kib}
 
@@ -15,6 +18,8 @@ either the *Management / Security / Roles* page in {kib} or the <<role-managemen
 to assign a specific <<kibana-privileges, Kibana privilege>> at that tenant. After creating the
 custom role, you should assign this role to the user(s) that you wish to have access.
 
+While multi-tenant installations are supported, the recommended approach to securing access to segments of {kib} is to grant users access to specific spaces.
+
 ==== Legacy roles
 
 Prior to {kib} 6.4, {kib} users required index privileges to the `kibana.index`

diff --git a/docs/spaces/getting-started.asciidoc b/docs/spaces/getting-started.asciidoc
@@ -0,0 +1,8 @@
+[role="xpack"]
+[[spaces-getting-started]]
+=== Getting Started
+
+Spaces are automatically enabled in {kib}. If you don't wish to use this feature, you can disable it
+by setting `xpack.spaces.enabled` to `false` in your `kibana.yml` configuration file.
+
+{kib} automatically creates a default space for you. If you are upgrading from another version of {kib}, then the default space will contain all of your existing saved objects. Although you can't delete the default space, you can customize it to your liking.
diff --git a/docs/spaces/images/delete-space.png b/docs/spaces/images/delete-space.png
diff --git a/docs/spaces/images/edit-space.png b/docs/spaces/images/edit-space.png
diff --git a/docs/spaces/images/securing-spaces.png b/docs/spaces/images/securing-spaces.png
diff --git a/docs/spaces/images/space-management.png b/docs/spaces/images/space-management.png
diff --git a/docs/spaces/images/space-selector.png b/docs/spaces/images/space-selector.png
diff --git a/docs/spaces/index.asciidoc b/docs/spaces/index.asciidoc
@@ -0,0 +1,17 @@
+[role="xpack"]
+[[xpack-spaces]]
+== Spaces
+
+With spaces, you can organize your dashboards and other saved objects into meaningful categories.
+After creating your own spaces, you will be asked to choose a space when you enter {kib}. Once inside a space,
+you will only see the dashboards and other saved objects that belong to that space. You can change your active space at any time.
+
+With security enabled, you can control which users have access to individual spaces.
+
+[role="screenshot"]
+image::spaces/images/space-selector.png["Space selector screen"]
+
+include::getting-started.asciidoc[]
+include::managing-spaces.asciidoc[]
+include::securing-spaces.asciidoc[]
+include::moving-saved-objects.asciidoc[]