Security

Kill Bill supports fine grained roles and permissions for the users accessing the system either through the UI or API. This can be useful in case of organizations looking to limit access across departments/teams etc. The endpoints in this group manage the users, roles and the associated permissions.

Please refer to our RBAC manual for more details.

Users

A user refers to any user or the api that maps to the user credential passed through the API.

User Roles Resource

A userRoles object contains the username, the password and the roles associated with the user.

Name	Type	Generated by	Description
username	string	user	Username for this user.
password	string	user	Password for this user.
roles	list	user	List of roles associated with this user.

Subject Resource

A Subject resource contains the information of the currently logged-in user as well as the related session information.

Name	Type	Generated by	Description
principal	string	user	Username for this user.
isAuthenticated	boolean	user	Is the user authenticated.
isRemembered	boolean	user	Specifies if `Remember Me` is checked for this user.
session	json	system	Session information for the user. Refer Session Resource for more information.

Role Definition Resource

A RoleDefinition resource contains the information of the permissions associated with a role.

Name	Type	Generated by	Description
role	string	user	Name of the role.
permissions	list	user	List of permissions associated with the role.

Session Resource

A Session resource contains the session information of the currently logged-in user.

Name	Type	Generated by	Description
id	string	system	UUID for this session.
startDate	datetime	system	Specifies the start date for the session in UTC.
lastAccessDate	datetime	system	Specifies the last access timestamp within the session in UTC.
timeout	long	system	Specifies the default time in ms that any session may remain idle before expiring.
host	string	system	Specifies the host information for the session.

List user permissions

Lists the permissions associated with the current API user.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/security/permissions

Query Parameters

None.

Response

If successful, returns a status code of 200 and a list of permissions associated with the current API user.

curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Accept: application/json" \
    "http://localhost:8080/1.0/kb/security/permissions"

import org.killbill.billing.client.api.gen.SecurityApi;
import org.killbill.billing.client.model.Strings;

SecurityApi securityApi = new SecurityApi(killBillHttpClient);

Strings currentUserPermissions = securityApi.getCurrentUserPermissions(requestOptions);

securityApi = KillBillClient::Model::Security

currentUserPermissions = securityApi.find_permissions(options)

securityApi = killbill.SecurityApi()

currentUserPermissions = securityApi.get_current_user_permissions()

const securityApi: killbill.SecurityApi = new killbill.SecurityApi(config);

const currentUserPermissions: AxiosResponse<string[],any> = await securityApi.getCurrentUserPermissions();

$apiInstance = $client->getSecurityApi();

$currentUserPermissions = $apiInstance->getCurrentUserPermissions();

[
  "invoice:commit",
  "invoice:item_adjust",
  "entitlement:pause_resume",
  "invoice:write_off",
  "account:credit",
  "account:create",
  "invoice:credit",
  "entitlement:cancel",
  "account:update",
  "invoice:void",
  "payment:transition",
  "account:charge",
  "payment:refund",
  "invoice:delete_cba",
  "invoice:dry_run",
  "payment:chargeback",
  "payment:trigger",
  "entitlement:transfer",
  "entitlement:create",
  "payment:notification",
  "entitlement:change_plan"
]

Get user information

Lists the session information associated with the currently logged-in (principal) user.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/security/subject

Query Parameters

None.

Response

If successful, returns a status code of 200 and the session information associated with the current API user.

curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Accept: application/json" \
    "http://localhost:8080/1.0/kb/security/subject"

import org.killbill.billing.client.api.gen.SecurityApi;
import org.killbill.billing.client.model.gen.Subject;

SecurityApi securityApi = new SecurityApi(killBillHttpClient);

Subject currentUserSubject = securityApi.getCurrentUserSubject(requestOptions);

securityApi = KillBillClient::Model::Security

currentUserSubject = securityApi.find_subject(options)

securityApi = killbill.SecurityApi()

currentUserSubject = securityApi.get_current_user_subject()

const securityApi: killbill.SecurityApi = new killbill.SecurityApi(config);

const currentUserSubject: AxiosResponse<killbill.Subject,any> = await securityApi.getCurrentUserSubject();

$apiInstance = $client->getSecurityApi();

$currentUserSubject = $apiInstance->getCurrentUserSubject();

{
  "principal": "admin",
  "isAuthenticated": true,
  "isRemembered": false,
  "session": {
    "id": "f6738239-b803-4fa5-85b9-b3ad13a8312c",
    "startDate": "2023-11-12T07:17:56.856Z",
    "lastAccessDate": "2023-11-12T07:27:03.792Z",
    "timeout": 3600000,
    "host": "0:0:0:0:0:0:0:1"
  }
}

Add a new user with roles

Create a new user (username, password, associated roles).

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/security/users

Request Body

A UserRoles object consisting of the username, password and the roles to be associated with the user. The required attributes are username,password,roles.

Query Parameters

None.

Response

If successful, returns a status code of 201 and the UserRoles object for the newly created user.

curl -v \
    -X POST \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d '{ "username": "testUserName", "password": "testUserPassword", "roles": ["TestRole"]}' \
    "http://localhost:8080/1.0/kb/security/users"

import org.killbill.billing.client.api.gen.SecurityApi;
import org.killbill.billing.client.model.gen.UserRoles;

SecurityApi securityApi = new SecurityApi(killBillHttpClient);

List<String> roles = List.of("TestRole");

UserRoles userRoles = new UserRoles();

userRoles.setUsername("TestUserName");
userRoles.setPassword("TestUserPassword");
userRoles.setRoles(roles);

UserRoles newUserDetails = securityApi.addUserRoles(userRoles, requestOptions);

user = 'user'
reason = 'reason'
comment = 'comment'

userRoles = KillBillClient::Model::UserRoles.new

userRoles.username = 'TestUserName'
userRoles.password = 'TestUserPassword'
userRoles.roles = ['TestRole']

userRoles.create(user,reason,comment,options)

securityApi = killbill.SecurityApi()

userBody = killbill.UserRoles(username = 'testUserName',
                              password = 'testUserPassword',
                              roles=['TestRole','finance'])

securityApi.add_user_roles(userBody,
                           created_by='demo',
                           reason='reason', 
                           comment='comment')

const securityApi: killbill.SecurityApi = new killbill.SecurityApi(config);

const body: killbill.UserRoles = {username: 'testUserName',
                                  password: 'testUserPassword',
                                  roles: ['TestRole', 'finance']};

securityApi.addUserRoles(body,'created_by');

$apiInstance = $client->getSecurityApi();

$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";

$body = new UserRoles();

$body->setUsername('TestUserName');
$body->setPassword('TestUserPassword');
$body->setRoles(['TestRole']);

$apiInstance->addUserRoles($body,$xKillbillCreatedBy,$xKillbillReason,$xKillbillComment);

Update a user password

Updates the password for a user.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/security/users/{username}/password

Request Body

A userRoles object consisting of the username, password and the roles to be associated with the user. The required attributes are username,password,roles.

Query Parameters

None

Response

If successful, returns a status code of 204 and an empty body.

curl -v \
    -X PUT \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d '{ "username": "testUserName", "password": "Updatedpassword"}' \
    "http://localhost:8080/1.0/kb/security/users/{username}/password"

import org.killbill.billing.client.api.gen.SecurityApi;
import org.killbill.billing.client.model.gen.UserRoles;

SecurityApi securityApi = new SecurityApi(killBillHttpClient);

String userName = "TestUserName";

UserRoles userRoles = new UserRoles();

userRoles.setPassword("TestUserPassUpdated");    

securityApi.updateUserPassword(userName, userRoles, requestOptions);

user = 'user'
reason = 'reason'
comment = 'comment'

userRoles = KillBillClient::Model::UserRoles.new

userRoles.username = 'userName'
userRoles.password = 'userNameUpdatedpassword'

userRoles.update(user,reason,comment,options)

securityApi = killbill.SecurityApi()

userRoles = killbill.UserRoles(username='userName',
                               password='userNameUpdatedpassword',
                               roles=['TestRole'])

securityApi.update_user_password('userName',
                                  userRoles,
                                  created_by='demo',
                                  reason='reason', 
                                  comment='comment')

const securityApi: killbill.SecurityApi = new killbill.SecurityApi(config);

const body: killbill.UserRoles = {username: 'userName',
                                  password: 'userNameUpdatedpassword',
                                  roles: ['TestRole', 'finance']};

securityApi.updateUserPassword(body, 'userName', 'created_by');

$apiInstance = $client->getSecurityApi();

$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";

$body = new UserRoles();

$body->setUsername('TestUserName');
$body->setPassword('TestUserUpdatedPassword');
$body->setRoles(['TestRole']);

$apiInstance->updateUserPassword($body,$xKillbillCreatedBy,$xKillbillReason,$xKillbillComment);

Get roles associated with a user

Lists the roles associated with a user.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/security/users/{username}/roles

Query Parameters

None

Response

If successful, returns a status code of 200 and a UserRoles object.

curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Accept: application/json" \
    "http://localhost:8080/1.0/kb/security/users/{username}/roles"

import org.killbill.billing.client.api.gen.SecurityApi;
import org.killbill.billing.client.model.gen.UserRoles;

SecurityApi securityApi = new SecurityApi(killBillHttpClient);

String userName = "testuser";

UserRoles userRoles = securityApi.getUserRoles(userName, requestOptions);

userRoles = KillBillClient::Model::UserRoles.new

userRoles.username = 'testuser'

userRoles.list(options)

securityApi = killbill.SecurityApi()

userRoles = securityApi.get_user_roles('testUser')

const securityApi: killbill.SecurityApi = new killbill.SecurityApi(config);

const response: AxiosResponse<killbill.UserRoles,any> = await securityApi.getUserRoles('testUser');

$apiInstance = $client->getSecurityApi();

$username = 'testUser';

$userRoles = $apiInstance->getUserRoles($username);

{
  "username": "testUser",
  "password": null,
  "roles": [
    "TestRole"
  ]
}

Update roles associated with a user

Updates the roles associated with a user.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/security/users/{username}/roles

Request Body

A userRoles object consisting of the username, password and the roles to be associated with the user. The required attributes are username,password,roles.

Query Parameters

None

Response

If successful, returns a status code of 204 and an empty body.

curl -v \
    -X PUT \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \
    -d '{"roles":["TestRole"]}' \
    "http://localhost:8080/1.0/kb/security/users/{username}/roles"

import org.killbill.billing.client.api.gen.SecurityApi;
import org.killbill.billing.client.model.gen.UserRoles;

SecurityApi securityApi = new SecurityApi(killBillHttpClient);

List<String> roles = List.of("UpdatedRole");

UserRoles userRoles = new UserRoles();

String userName = "TestUser";

userRoles.setRoles(roles);

securityApi.updateUserRoles(userName, userRoles, requestOptions);

user = 'user'
reason = 'reason'
comment = 'comment'

userRoles = KillBillClient::Model::UserRoles.new

userRoles.username = 'TestUser'
userRoles.roles = ['UpdatedRole']

userRoles.update(user,reason,comment,options)

securityApi = killbill.SecurityApi()

userRoles = killbill.UserRoles(username='testUser',                               
                               roles=['TestRole'])

securityApi.update_user_roles('testUser',
                               userRoles,
                               created_by='demo',
                               reason='reason', 
                               comment='comment')

const securityApi: killbill.SecurityApi = new killbill.SecurityApi(config);

const body: killbill.UserRoles = {username: 'testUser',
                                  password: 'testUserPassword',
                                  roles: ['TestRole']};

securityApi.updateUserRoles(body, 'testUser', 'created_by');

$apiInstance = $client->getSecurityApi();

$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";

$body = new UserRoles();

$body->setUsername('TestUserName');
$body->setPassword('TestUserPassword');
$body->setRoles(['TestUpdatedRole']);

$apiInstance->updateUserRoles($body,$xKillbillCreatedBy,$xKillbillReason,$xKillbillComment);

Invalidate an existing user

Invalidates a user.

HTTP Request

DELETE http://127.0.0.1:8080/1.0/kb/security/users/{username}

Query Parameters

None

Response

If successful, returns a status code of 204 and an empty body.

curl -v \
    -X DELETE \
    -u admin:password \
    -H "X-Killbill-ApiKey: bob" \
    -H "X-Killbill-ApiSecret: lazar" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -H "X-Killbill-CreatedBy: demo" \
    -H "X-Killbill-Reason: demo" \
    -H "X-Killbill-Comment: demo" \    
    "http://localhost:8080/1.0/kb/security/users/{username}"

import org.killbill.billing.client.api.gen.SecurityApi;

SecurityApi securityApi = new SecurityApi(killBillHttpClient);

String userName = "testuser";

securityApi.invalidateUser(userName, requestOptions);

user = 'user'
reason = 'reason'
comment = 'comment'

userRoles = KillBillClient::Model::UserRoles.new

userRoles.username = 'TestUser'

userRoles.destroy(user,reason,comment,options)

securityApi = killbill.SecurityApi()

securityApi.invalidate_user('testUser',
                             created_by='demo',
                             reason='reason', 
                             comment='comment')

const securityApi: killbill.SecurityApi = new killbill.SecurityApi(config);

securityApi.invalidateUser('testUser', 'created_by');

$apiInstance = $client->getSecurityApi();

$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";

$username = 'username';

$apiInstance->invalidateUser($username,$xKillbillCreatedBy,$xKillbillReason,$xKillbillComment);

Roles

Kill Bill allows to segregate permissions associated with a user by defining the roles assigned to the user. For example, a user having finance role can have permissions associated to the payments, viewing invoice etc. whereas a user having sales role can have permissions to generate invoices, viewing payments etc.

Retrieve a role definition

Retrieve an existing role definition.

HTTP Request

GET http://127.0.0.1:8080/1.0/kb/security/roles/{role}

Query Parameters

None.

Response

If successful, returns a status code of 200 and the role object with associated permissions.

curl -v \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Accept: application/json" \
     'http://127.0.0.1:8080/1.0/kb/security/roles/{role}'

import org.killbill.billing.client.api.gen.SecurityApi;
import org.killbill.billing.client.model.gen.RoleDefinition;

SecurityApi securityApi = new SecurityApi(killBillHttpClient);

String role = "TestRole";

RoleDefinition roleDefinition = securityApi.getRoleDefinition(role, requestOptions);


role = 'TestRole'

roleDef = KillBillClient::Model::RoleDefinition.find_by_name(role, options)

securityApi = killbill.SecurityApi()

role = 'TestRole'

roleDefinition = securityApi.get_role_definition(role)

const securityApi: killbill.SecurityApi = new killbill.SecurityApi(config);

const roleDefinition:AxiosResponse<killbill.RoleDefinition,any> = await securityApi.getRoleDefinition('TestRole');

$apiInstance = $client->getSecurityApi();

$role = 'TestRole';

$roleDefinition = $apiInstance->getRoleDefinition($role);

{
  "role": "ROLE",
  "permissions": [
    "account:*",
    "invoice:trigger"
  ]
}

Add a role definition

Create a new role definition.

HTTP Request

POST http://127.0.0.1:8080/1.0/kb/roles

Request Body

A RoleDefinition object consisting of the role and the list of permissions to be associated with the role. The required attributes are role and the associated permissions.

Query Parameters

None.

Response

If successful, returns a status code of 201 and an empty body.

curl -v \
     -X POST \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Content-Type: application/json" \
     -H "X-Killbill-CreatedBy: demo" \
     -d '{
             "role": "ROLE",
             "permissions": ["account:*","invoice:trigger"]
     }' \
     'http://127.0.0.1:8080/1.0/kb/security/roles'

import org.killbill.billing.client.api.gen.SecurityApi;
import org.killbill.billing.client.model.gen.RoleDefinition;

SecurityApi securityApi = new SecurityApi(killBillHttpClient);

List<String> permissions = List.of("account:*", "invoice:trigger");

String role = "TestRole";

RoleDefinition roleDefinition = new RoleDefinition();
roleDefinition.setRole(role);
roleDefinition.setPermissions(permissions);

RoleDefinition newRoleDefinition = securityApi.addRoleDefinition(roleDefinition, requestOptions);

user = 'user'
reason = 'reason'
comment = 'comment'

roleDef = KillBillClient::Model::RoleDefinition.new

roleDef.role = 'testRole17thDec'
roleDef.permissions = ["account:*", "invoice:trigger"]

roleDef.create(user,reason,comment,options)

securityApi = killbill.SecurityApi()

roleDefinition =killbill.RoleDefinition(role='TestRole',
                                        permissions=["account:*","invoice:trigger"])

securityApi.add_role_definition(roleDefinition,
                                created_by='demo',
                                reason='reason', 
                                comment='comment')

const securityApi: killbill.SecurityApi = new killbill.SecurityApi(config);

const body: killbill.RoleDefinition = {role: 'TestRole',
                                       permissions: ['account:*', 'invoice:trigger']};

securityApi.addRoleDefinition(body, 'created_by');

$apiInstance = $client->getSecurityApi();

$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";

$roleDefinition = new RoleDefinition();

$roleDefinition->setRole('TestRole');
$roleDefinition->setPermissions(['account:*', 'invoice:trigger']);

$apiInstance->addRoleDefinition($roleDefinition,$xKillbillCreatedBy,$xKillbillReason,$xKillbillComment);

Update a role definition

Update an existing role permissions.

HTTP Request

PUT http://127.0.0.1:8080/1.0/kb/roles

Request Body

A RoleDefinition object consisting of the role and the list of permissions to be associated with the role. The required attributes are role and the associated permissions.

Query Parameters

None.

Response

If successful, returns a status code of 204 and an empty body.

curl -v \
     -X PUT \
     -u admin:password \
     -H "X-Killbill-ApiKey: bob" \
     -H "X-Killbill-ApiSecret: lazar" \
     -H "Content-Type: application/json" \
     -H "X-Killbill-CreatedBy: demo" \
     -d '{
             "role": "ROLE",
             "permissions": ["account:*"]
     }' \
     'http://127.0.0.1:8080/1.0/kb/security/roles'

import org.killbill.billing.client.api.gen.SecurityApi;
import org.killbill.billing.client.model.gen.RoleDefinition;

SecurityApi securityApi = new SecurityApi(killBillHttpClient);

List<String> permissions = List.of("account:*", "invoice:trigger");

String role = "TestRole";

RoleDefinition roleDefinition = new RoleDefinition();
roleDefinition.setRole(role);
roleDefinition.setPermissions(permissions);

securityApi.updateRoleDefinition(roleDefinition, requestOptions);

user = 'user'
reason = 'reason'
comment = 'comment'

roleDef = KillBillClient::Model::RoleDefinition.new

roleDef.role = 'TestRole'
roleDef.permissions = ["account:*", "invoice:trigger"]

roleDef.update(user,reason,comment,options)

securityApi = killbill.SecurityApi()

roleDefinition =killbill.RoleDefinition(role='TestRole',
                                        permissions=["invoice:trigger"])

securityApi.update_role_definition(roleDefinition,'KB')

const securityApi: killbill.SecurityApi = new killbill.SecurityApi(config);

const body: killbill.RoleDefinition = {role: 'TestRole',
                                       permissions: ['invoice:trigger']};

securityApi.updateRoleDefinition(body, 'created_by');

$apiInstance = $client->getSecurityApi();

$xKillbillCreatedBy = "user";
$xKillbillReason = "reason";
$xKillbillComment = "comment";

$roleDefinition = new RoleDefinition();

$roleDefinition->setRole('TestRole');
$roleDefinition->setPermissions(['account:*', 'invoice:*']);

$apiInstance->updateRoleDefinition($roleDefinition,$xKillbillCreatedBy,$xKillbillReason,$xKillbillComment);