RBAC API Reference

Be sure to review the RBAC overview before exploring the RBAC API below.

Add A User

Endpoint

/rbac/users

Request Body

Attribute	Description
`name`	The RBAC user name.
`user_token` optional	The authentication token to be presented to the Admin API. If this value is not present, the token will automatically be generated.
`enabled` optional	A flag to enable or disable the user. By default, users are enabled.
`comment` optional	A string describing the RBAC user object.

Response

HTTP 201 Created

{
 "created_at": 1501395904000, 
 "enabled": true, 
 "id": "283fccff-2d4f-49a9-8730-dc8b71ec2245", 
 "name": "bob", 
 "user_token": "9CiAvvgnqCQmarplngmT3rJImEujOw7m"
}

Retrieve A User

Endpoint

/rbac/users/{name_or_id}

Attribute	Description
`name_or_id`	The RBAC user name or UUID.

Response

HTTP 200 OK

{
 "created_at": 1501395904000, 
 "enabled": true, 
 "id": "283fccff-2d4f-49a9-8730-dc8b71ec2245", 
 "name": "bob", 
 "user_token": "9CiAvvgnqCQmarplngmT3rJImEujOw7m"
}

List Users

Endpoint

/rbac/users/

Response

HTTP 200 OK

{
 "data": [
  {
   "created_at": 1501524409000, 
   "enabled": true, 
   "id": "11cbd5cf-e4e0-47b6-968b-73b062440a4e", 
   "name": "bob", 
   "user_token": "1VHzdFqU24GmoeAlsoE7V95gWn1OoPjS"
  }
 ], 
 "total": 1
}

Update A User

Endpoint

/rbac/users/{name_or_id}

Attribute	Description
`name_or_id`	The RBAC user name or UUID.
`user_token` optional	The authentication token to be presented to the Admin API. If this value is not present, the token will automatically be generated.
`enabled` optional	A flag to enable or disable the user. By default, users are enabled.
`comment` optional	A string describing the RBAC user object.

Response

HTTP 200 OK

{
 "created_at": 1501395904000, 
 "enabled": true, 
 "id": "283fccff-2d4f-49a9-8730-dc8b71ec2245", 
 "name": "bob", 
 "user_token": "9CiAvvgnqCQmarplngmT3rJImEujOw7m"
}

Delete a User

Endpoint

/rbac/users/{name_or_id}

Response

HTTP 204 No Content

Add a Role

Endpoint

/rbac/roles

Attribute	Description
`name`	The RBAC user name.
`comment` optional	A string describing the RBAC user object.

Response

HTTP 201 Created

{
 "created_at": 1501395904000, 
 "id": "8ddc36ee-dde0-4daa-baae-6868f4514256", 
 "name": "read-only"
}

Retrieve a Role

Endpoint

/rbac/role{name_or_id}

Attribute	Description
`name_or_id`	The RBAC role name or UUID.

Response

HTTP 200 OK

{
 "created_at": 1501395904000, 
 "id": "8ddc36ee-dde0-4daa-baae-6868f4514256", 
 "name": "read-only"
}

List Roles

Endpoint

/rbac/roles

Response

HTTP 200 OK

{
 "data": [
  {
   "created_at": 1501524270000, 
   "id": "9bd49829-2a8b-41fd-b7fc-28e63c100676", 
   "name": "read-only"
  }
 ], 
 "total": 3
}

Update A Role

Endpoint

/rbac/roles/{name_or_id}

Attribute	Description
`name`	The RBAC role name or UUID.
`comment` optional	A string describing the RBAC role object.

Response

HTTP 200 OK

{
 "created_at": 1501395904000, 
 "enabled": true, 
 "id": "283fccff-2d4f-49a9-8730-dc8b71ec2245", 
 "name": "bob", 
 "user_token": "9CiAvvgnqCQmarplngmT3rJImEujOw7m"
}

Delete A Role

Endpoint

/rbac/role/{name_or_id}

Response

HTTP 204 No Content

Add A Permission

Endpoint

/rbac/permissions

Request Body

Attribute	Description
`name`	The RBAC permisson name.
`negative`	If true, explicitly disallow the actions associated with the permissions tied to this resource. By default this value is false.
`resources`	One or more RBAC resource names associated with this permission.
`actions`	One or more actions associated with this permission.
`comment` optional	A string describing the RBAC permission object.

Response

HTTP 201 Created

{
 "actions": [
  "read", 
  "delete", 
  "create", 
  "update"
 ], 
 "created_at": 1501524737000, 
 "id": "d881bd36-00ca-404f-b428-427b2eab0184", 
 "name": "apis-all", 
 "negative": false, 
 "resources": [
  "apis"
 ]
}

Retrieve A Permission

Endpoint

/rbac/permissions/{name_or_id}

Attribute	Description
`name_or_id`	The RBAC permisson name or UUID.

Response

HTTP 200 OK

{
 "actions": [
  "read", 
  "delete", 
  "create", 
  "update"
 ], 
 "created_at": 1501524737000, 
 "id": "d881bd36-00ca-404f-b428-427b2eab0184", 
 "name": "apis-all", 
 "negative": false, 
 "resources": [
  "apis"
 ]
}

List Permissions

Endpoint

/rbac/permissions/

Response

HTTP 200 OK

{
 "data": [
  {
   "actions": [
    "read", 
    "delete", 
    "create", 
    "update"
   ], 
   "created_at": 1501524737000, 
   "id": "d881bd36-00ca-404f-b428-427b2eab0184", 
   "name": "apis-all", 
   "negative": false, 
   "resources": [
    "apis"
   ]
  }, 
 ], 
 "total": 6
}

Update a Permission

Endpoint

/rbac/permissions/{name_or_id}

Request Body

Attribute	Description
`name_or_id`	The RBAC permisson name or UUID.
`negative`	If true, explicitly disallow the actions associated with the permissions tied to this resource. By default this value is false.
`resources`	One or more RBAC resource names associated with this permission.
`actions`	One or more actions associated with this permission.
`comment` optional	A string describing the RBAC permission object

Response

HTTP 200 OK

{
 "actions": [
  "read", 
  "delete", 
  "create", 
  "update"
 ], 
 "created_at": 1501524737000, 
 "id": "d881bd36-00ca-404f-b428-427b2eab0184", 
 "name": "apis-all", 
 "negative": false, 
 "resources": [
  "apis"
 ]
}

Delete A Permission

Endpoint

/rbac/permissions/{name_or_id}

Response

HTTP 204 No Content

Add a User to a Role

Endpoint

/rbac/permissions/{name_or_id}/roles

Request Body

Attribute	Description
`roles`	Comma-separated list of role names to assign to the user.

Response

HTTP 201 Created

{
 "roles": [
  {
   "comment": "Read-only access across all initial RBAC resources", 
   "created_at": 1501524270000, 
   "id": "9bd49829-2a8b-41fd-b7fc-28e63c100676", 
   "name": "read-only"
  }
 ], 
 "user": {
  "created_at": 1501524409000, 
  "enabled": true, 
  "id": "11cbd5cf-e4e0-47b6-968b-73b062440a4e", 
  "name": "bob", 
  "user_token": "1VHzdFqU24GmoeAlsoE7V95gWn1OoPjS"
 }
}

List a User's Roles

Endpoint

/rbac/permissions/{name_or_id}/roles

Response

HTTP 200 OK

{
 "roles": [
  {
   "comment": "Read-only access across all initial RBAC resources", 
   "created_at": 1501524270000, 
   "id": "9bd49829-2a8b-41fd-b7fc-28e63c100676", 
   "name": "read-only"
  }
 ], 
 "user": {
  "created_at": 1501524409000, 
  "enabled": true, 
  "id": "11cbd5cf-e4e0-47b6-968b-73b062440a4e", 
  "name": "bob", 
  "user_token": "1VHzdFqU24GmoeAlsoE7V95gWn1OoPjS"
 }
}

List a User's Permissions

Endpoint

/rbac/permissions/{name_or_id}/permissions

Response

HTTP 200 OK

{
 "apis": [
  "read"
 ], 
 "plugins": [
  "read",
  "create",
  "update",
  "delete"
 ]
}

Delete a Role from a User

Endpoint

/rbac/permissions/{name_or_id}/roles

Request Body

Attribute	Description
`roles`	Comma-separated list of role names to assign to the user.

Response

HTTP 204 No Content

Add a Permission to a Role

Endpoint

/rbac/permissions/{name_or_id}/permissions

Request Body

Attribute	Description
`permissions`	Comma-separated list of permission names to assign to the role.

Response

HTTP 201 Created

{
 "permissions": [
  {
   "actions": [
    "read"
   ], 
   "comment": "Read-only permissions across all initial RBAC resources", 
   "created_at": 1501524270000, 
   "id": "6f835b92-86b1-4b9d-8a91-f9a66c1940ce", 
   "name": "read-only", 
   "negative": false, 
   "resources": [
    "default", 
    "kong", 
    "status", 
    "apis", 
    "plugins", 
    "cache", 
    "certificates", 
    "consumers", 
    "snis", 
    "upstreams", 
    "targets", 
    "rbac", 
    "key-auth", 
    "jwt", 
    "acls", 
    "basic-auth", 
    "oauth2", 
    "hmac-auth"
   ]
  }
 ], 
 "role": {
  "created_at": 1501524295000, 
  "id": "8ddc36ee-dde0-4daa-baae-6868f4514256", 
  "name": "read-only"
 }
}

List a Role's Permissions

Endpoint

/rbac/permissions/{name_or_id}/permissions

Response

200 OK

{
 "permissions": [
  {
   "actions": [
    "read"
   ], 
   "comment": "Read-only permissions across all initial RBAC resources", 
   "created_at": 1501524270000, 
   "id": "6f835b92-86b1-4b9d-8a91-f9a66c1940ce", 
   "name": "read-only", 
   "negative": false, 
   "resources": [
    "default", 
    "kong", 
    "status", 
    "apis", 
    "plugins", 
    "cache", 
    "certificates", 
    "consumers", 
    "snis", 
    "upstreams", 
    "targets", 
    "rbac", 
    "key-auth", 
    "jwt", 
    "acls", 
    "basic-auth", 
    "oauth2", 
    "hmac-auth"
   ]
  }
 ], 
 "role": {
  "created_at": 1501524295000, 
  "id": "8ddc36ee-dde0-4daa-baae-6868f4514256", 
  "name": "read-only"
 }
}

Delete A Permission from a Role

Endpoint

/rbac/permissions/{name_or_id}/permissions

Request Body

Attribute	Description
`permissions`	Comma-separated list of permission names to remove from the user.

Response

204 No Content

List Available RBAC Resources

Endpoint

/rbac/resources

Response

200 OK

[
 "plugins", 
 "cache", 
 "targets", 
 "basic-auth", 
 "key-auth", 
 "hmac-auth", 
 "snis", 
 "certificates", 
 "kong", 
 "acls", 
 "status", 
 "jwt", 
 "rbac", 
 "apis", 
 "upstreams", 
 "consumers", 
 "oauth2"
]