Workspaces Reference

Kong Gateway’s Workspaces feature is configurable through Kong’s Admin API.

Workspace Object

The Workspace object describes the Workspace entity, which has an ID and a name.

Add Workspace

Endpoint

/workspaces/

Request Body

AttributeDescription
nameThe Workspace name.

Response

  1. HTTP 201 Created
  1. {
  2.   "comment": null,
  3.   "config": {
  4.     "meta": null,
  5.     "portal": false,
  6.     "portal_access_request_email": null,
  7.     "portal_approved_email": null,
  8.     "portal_auth": null,
  9.     "portal_auth_conf": null,
  10.     "portal_auto_approve": null,
  11.     "portal_cors_origins": null,
  12.     "portal_developer_meta_fields": "[{\"label\":\"Full Name\",\"title\":\"full_name\",\"validator\":{\"required\":true,\"type\":\"string\"}}]",
  13.     "portal_emails_from": null,
  14.     "portal_emails_reply_to": null,
  15.     "portal_invite_email": null,
  16.     "portal_reset_email": null,
  17.     "portal_reset_success_email": null,
  18.     "portal_token_exp": null
  19.   },
  20.   "created_at": 1557441226,
  21.   "id": "c663cca5-c6f6-474a-ae44-01f62aba16a9",
  22.   "meta": {
  23.     "color": null,
  24.     "thumbnail": null
  25.   },
  26.   "name": "green-team"
  27. }

List Workspaces

Endpoint

/workspaces/

Response

  1. HTTP 200 OK
  1. {
  2.   "data": [
  3.     {
  4.       "comment": null,
  5.       "config": {
  6.         "meta": null,
  7.         "portal": false,
  8.         "portal_access_request_email": null,
  9.         "portal_approved_email": null,
  10.         "portal_auth": null,
  11.         "portal_auth_conf": null,
  12.         "portal_auto_approve": null,
  13.         "portal_cors_origins": null,
  14.         "portal_developer_meta_fields": "[{\"label\":\"Full Name\",\"title\":\"full_name\",\"validator\":{\"required\":true,\"type\":\"string\"}}]",
  15.         "portal_emails_from": null,
  16.         "portal_emails_reply_to": null,
  17.         "portal_invite_email": null,
  18.         "portal_reset_email": null,
  19.         "portal_reset_success_email": null,
  20.         "portal_token_exp": null
  21.       },
  22.       "created_at": 1557419951,
  23.       "id": "00000000-0000-0000-0000-000000000000",
  24.       "meta": {
  25.         "color": null,
  26.         "thumbnail": null
  27.       },
  28.       "name": "default"
  29.     },
  30.     {
  31.       "comment": null,
  32.       "config": {
  33.         "meta": null,
  34.         "portal": false,
  35.         "portal_access_request_email": null,
  36.         "portal_approved_email": null,
  37.         "portal_auth": null,
  38.         "portal_auth_conf": null,
  39.         "portal_auto_approve": null,
  40.         "portal_cors_origins": null,
  41.         "portal_developer_meta_fields": "[{\"label\":\"Full Name\",\"title\":\"full_name\",\"validator\":{\"required\":true,\"type\":\"string\"}}]",
  42.         "portal_emails_from": null,
  43.         "portal_emails_reply_to": null,
  44.         "portal_invite_email": null,
  45.         "portal_reset_email": null,
  46.         "portal_reset_success_email": null,
  47.         "portal_token_exp": null
  48.       },
  49.       "created_at": 1557441226,
  50.       "id": "c663cca5-c6f6-474a-ae44-01f62aba16a9",
  51.       "meta": {
  52.         "color": null,
  53.         "thumbnail": null
  54.       },
  55.       "name": "green-team"
  56.     }
  57.   ],
  58.   "next": null
  59. }

Update or Create a Workspace

Endpoint

/workspaces/{id}

AttributesDescription
id
conditional		The Workspace’s unique ID, if replacing it.*
  • The behavior of PUT endpoints is the following: if the request payload does not contain an entity’s primary key (id for Workspaces), the entity will be created with the given payload. If the request payload does contain an entity’s primary key, the payload will “replace” the entity specified by the given primary key. If the primary key is not that of an existing entity, 404 NOT FOUND will be returned.

Request Body

AttributeDescription
nameThe Workspace name.

Response

If creating the entity:

  1. HTTP 201 Created

If replacing the entity:

  1. HTTP 200 OK
  1. {
  2.   "comment": null,
  3.   "config": {
  4.     "meta": null,
  5.     "portal": false,
  6.     "portal_access_request_email": null,
  7.     "portal_approved_email": null,
  8.     "portal_auth": null,
  9.     "portal_auth_conf": null,
  10.     "portal_auto_approve": null,
  11.     "portal_cors_origins": null,
  12.     "portal_developer_meta_fields": "[{\"label\":\"Full Name\",\"title\":\"full_name\",\"validator\":{\"required\":true,\"type\":\"string\"}}]",
  13.     "portal_emails_from": null,
  14.     "portal_emails_reply_to": null,
  15.     "portal_invite_email": null,
  16.     "portal_reset_email": null,
  17.     "portal_reset_success_email": null,
  18.     "portal_token_exp": null
  19.   },
  20.   "created_at": 1557504202,
  21.   "id": "c663cca5-c6f6-474a-ae44-01f62aba16a9",
  22.   "meta": {
  23.     "color": null,
  24.     "thumbnail": null
  25.   },
  26.   "name": "rocket-team"
  27. }

Retrieve a Workspace

Endpoint

/workspaces/{name or id}

AttributesDescription
name or id
required		The unique identifier or the name of the Workspace to retrieve

Response

  1. HTTP 200 OK
  1. {
  2.   "config": {
  3.     "portal": false,
  4.     "portal_developer_meta_fields": "[{\"label\":\"Full Name\",\"title\":\"full_name\",\"validator\":{\"required\":true,\"type\":\"string\"}}]"
  5.   },
  6.   "created_at": 1557504202,
  7.     "id": "c663cca5-c6f6-474a-ae44-01f62aba16a9",
  8.     "meta": { },
  9.   "name": "rocket-team"
  10. }

Retrieve Workspace Metadata

Endpoint

/workspaces/{name or id}/meta

AttributesDescription
name or id
required		The unique identifier or the name of the Workspace to retrieve

Response

  1. HTTP 200 OK
  1. {
  2.   "counts": {
  3.     "acls": 1,
  4.     "apis": 1,
  5.     "basicauth_credentials": 1,
  6.     "consumers": 1234,
  7.     "files": 41,
  8.     "hmacauth_credentials": 1,
  9.     "jwt_secrets": 1,
  10.     "keyauth_credentials": 1,
  11.     "oauth2_authorization_codes": 1,
  12.     "oauth2_credentials": 1,
  13.     "oauth2_tokens": 1,
  14.     "plugins": 5,
  15.     "rbac_roles": 3,
  16.     "rbac_users": 12,
  17.     "routes": 15,
  18.     "services": 2,
  19.     "ssl_certificates": 1,
  20.     "ssl_servers_names": 1,
  21.     "targets": 1,
  22.     "upstreams": 1
  23.   }
  24. }

Delete a Workspace

Endpoint

/workspaces/{name or id}

AttributesDescription
name or id
required		The unique identifier or the name of the Workspace to delete

Note: All entities within a Workspace must be deleted before the Workspace itself can be.

Response

  1. HTTP 204 No Content

Update a Workspace

Endpoint

/workspaces/{name or id}

AttributesDescription
name or id
required		The unique identifier or the name of the Workspace to patch

Request Body

AttributesDescription
commentA string describing the Workspace

The behavior of PATCH endpoints prevents the renaming of a Workspace.

Response

  1. HTTP 200 OK
  1. {
  2.   "comment": "this is a sample comment in the patch request",
  3.   "config": {
  4.     "meta": null,
  5.     "portal": false,
  6.     "portal_access_request_email": null,
  7.     "portal_approved_email": null,
  8.     "portal_auth": null,
  9.     "portal_auth_conf": null,
  10.     "portal_auto_approve": null,
  11.     "portal_cors_origins": null,
  12.     "portal_developer_meta_fields": "[{\"label\":\"Full Name\",\"title\":\"full_name\",\"validator\":{\"required\":true,\"type\":\"string\"}}]",
  13.     "portal_emails_from": null,
  14.     "portal_emails_reply_to": null,
  15.     "portal_invite_email": null,
  16.     "portal_reset_email": null,
  17.     "portal_reset_success_email": null,
  18.     "portal_token_exp": null
  19.   },
  20.   "created_at": 1557509909,
  21.   "id": "c543d2c8-d297-4c9c-adf5-cd64212868fd",
  22.   "meta": {
  23.     "color": null,
  24.     "thumbnail": null
  25.   },
  26.   "name": "green-team"
  27. }