Module: Auth0::Api::V2::Roles

Includes:
Mixins::Validation
Included in:
Auth0::Api::V2
Defined in:
lib/auth0/api/v2/roles.rb

Overview

Methods to use the Roles endpoints

Instance Method Summary collapse

Methods included from Mixins::Validation

#validate_permissions_array, #validate_strings_array

Instance Method Details

#add_role_permissions(role_id, permissions) ⇒ Object

Associate permissions with a Role. Required scope: “update:roles”

Parameters:

  • role_id (string) —

    Role ID to add permissions.

  • permissions (array) —

    Array of Permission structs to add.

Raises:

See Also:



147
148
149
150
151
152
 
# File 'lib/auth0/api/v2/roles.rb', line 147

def add_role_permissions(role_id, permissions)
  raise Auth0::MissingParameter, 'Must supply a valid role_id' if role_id.to_s.empty?

  permissions = validate_permissions_array(permissions)
  post "#{roles_path}/#{role_id}/permissions", permissions: permissions
end

#add_role_users(role_id, users = []) ⇒ Object

Add one or more Users to a Role. Required scopes: “update:roles”

Parameters:

  • role_id (string) —

    Role ID to add Users.

  • users (array) (defaults to: []) —

    Array of string User IDs to add to the Role.

Raises:

See Also:



112
113
114
115
116
117
 
# File 'lib/auth0/api/v2/roles.rb', line 112

def add_role_users(role_id, users = [])
  raise Auth0::MissingParameter, 'Must supply a valid role_id' if role_id.to_s.empty?

  validate_strings_array(users)
  post "#{roles_path}/#{role_id}/users", users: users
end

#create_role(role_name, data = {}) ⇒ Object

Create a new Role. Required scope: “create:roles”

Parameters:

  • role_name (string) —

    Role name for the new Role.

  • data (hash) (defaults to: {}) —

    Additional Role data.

Raises:

See Also:



50
51
52
53
54
55
 
# File 'lib/auth0/api/v2/roles.rb', line 50

def create_role(role_name, data = {})
  raise Auth0::MissingParameter, 'Must supply a valid role_name' if role_name.to_s.empty?

  data[:name] = role_name
  post roles_path.to_s, data
end

#delete_role(role_id) ⇒ Object

Delete a single Role by ID. Required scope: “delete:roles”

Parameters:

  • role_id (string) —

    Role ID to delete.

Raises:

See Also:



74
75
76
77
78
 
# File 'lib/auth0/api/v2/roles.rb', line 74

def delete_role(role_id)
  raise Auth0::MissingParameter, 'Must supply a valid role_id' if role_id.to_s.empty?

  delete "#{roles_path}/#{role_id}"
end

#get_role(role_id) ⇒ json Also known as: role

Get a single Role by ID. Required scope: “read:roles”

Parameters:

  • role_id (string) —

    Role ID to get.

Returns:

  • (json) —

    Role data.

Raises:

See Also:



37
38
39
40
41
 
# File 'lib/auth0/api/v2/roles.rb', line 37

def get_role(role_id)
  raise Auth0::MissingParameter, 'Must supply a valid role_id' if role_id.to_s.empty?

  get "#{roles_path}/#{role_id}"
end

#get_role_permissions(role_id, options = {}) ⇒ json

Get the permissions associated to a Role. Required scope: “read:roles”

Parameters:

  • role_id (string) —

    Role ID to add permissions.

  • options (hash) (defaults to: {}) —

    A hash of options for getting permissions

    • per_page: Number or permissions to return.

    • page: Page number to return, zero-based

    • include_totals: True to include query summary in the result, false or nil otherwise.

Returns:

  • (json) —

    All permissions matching the query.

Raises:

See Also:



130
131
132
133
134
135
136
137
138
139
 
# File 'lib/auth0/api/v2/roles.rb', line 130

def get_role_permissions(role_id, options = {})
  raise Auth0::MissingParameter, 'Must supply a valid role_id' if role_id.to_s.empty?

  request_params = {
    per_page: options.fetch(:per_page, nil),
    page: options.fetch(:page, nil),
    include_totals: options.fetch(:include_totals, nil)
  }
  get "#{roles_path}/#{role_id}/permissions", request_params
end

#get_role_users(role_id, options = {}) ⇒ Object

Get Users assigned to a specific Role. Required scopes:

- "read:roles"
- "read:users"

Parameters:

  • role_id (string) —

    Role ID to which the Users belong to.

  • options (hash) (defaults to: {}) —

    A hash of options for getting Roles

    • per_page: Number of Roles to return.

    • page: Page number to return, zero-based.

    • :from [string] For checkpoint pagination, the ID from which to start selection from.

    • :take [integer] For checkpoint pagination, the number of entries to retrieve. Default is 50.

    • :include_totals [boolean] True to include query summary in the result, false or nil otherwise.

Raises:

See Also:



93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/auth0/api/v2/roles.rb', line 93

def get_role_users(role_id, options = {})
  raise Auth0::MissingParameter, 'Must supply a valid role_id' if role_id.to_s.empty?

  request_params = {
    per_page:       options.fetch(:per_page, nil),
    page:           options.fetch(:page, nil),
    from:           options.fetch(:from, nil),
    take:           options.fetch(:take, nil),
    include_totals: options.fetch(:include_totals, nil)
  }
  get "#{roles_path}/#{role_id}/users", request_params
end

#get_roles(options = {}) ⇒ json Also known as: roles

Get all Roles Required scope: “read:roles”

Parameters:

  • options (hash) (defaults to: {}) —

    A hash of options for getting Roles

    • per_page: Number of Roles to return.

    • page: Page number to return, zero-based.

    • include_totals: True to include query summary in the result, false or nil otherwise.

    • name_filter: Optional filter on name (case-insensitive).

Returns:

  • (json) —

    All Roles matching the query.

See Also:



19
20
21
22
23
24
25
26
27
 
# File 'lib/auth0/api/v2/roles.rb', line 19

def get_roles(options = {})
  request_params = {
    per_page: options.fetch(:per_page, nil),
    page: options.fetch(:page, nil),
    include_totals: options.fetch(:include_totals, nil),
    name_filter: options.fetch(:name_filter, nil)
  }
  get roles_path, request_params
end

#remove_role_permissions(role_id, permissions) ⇒ Object

Remove permissions from a Role. Required scope: “update:roles”

Parameters:

  • role_id (string) —

    Role ID to remove permissions.

  • permissions (array) —

    Array of Permission structs to remove.

Raises:

See Also:



160
161
162
163
164
165
 
# File 'lib/auth0/api/v2/roles.rb', line 160

def remove_role_permissions(role_id, permissions)
  raise Auth0::MissingParameter, 'Must supply a valid role_id' if role_id.to_s.empty?

  permissions = validate_permissions_array(permissions)
  delete_with_body("#{roles_path}/#{role_id}/permissions", permissions: permissions)
end

#update_role(role_id, data = {}) ⇒ Object

Update a Role by ID. Required scope: “update:roles”

Parameters:

  • role_id (string) —

    Role ID to update.

  • data (string) (defaults to: {}) —

    Role data to update.

Raises:

See Also:



63
64
65
66
67
 
# File 'lib/auth0/api/v2/roles.rb', line 63

def update_role(role_id, data = {})
  raise Auth0::MissingParameter, 'Must supply a valid role_id' if role_id.to_s.empty?

  patch "#{roles_path}/#{role_id}", data
end