Careful! You are browsing documentation for an outdated version of Kong. Go here to browse the documentation for the latest version.

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/users/{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/users/{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/users/{name_or_id}/permissions

Response

HTTP 200 OK

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

Delete a Role from a User

Endpoint

/rbac/users/{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/roles/{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/roles/{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/roles/{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"
]