In order to give you better service we use cookies. By continuing to use our website, you agree to the use of cookies as described in our Cookie Policy

Kong Logo
Edit this Page
Documentation

RBAC API

Careful! You are browsing documentation for an outdated version of Kong. Go here to browse the documentation for the latest version.
Estimated reading time: 13 minutes

Table of Contents

Introduction

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"
]