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:


143
144
145
146
147
148
# File 'lib/auth0/api/v2/roles.rb', line 143

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:


108
109
110
111
112
113
# File 'lib/auth0/api/v2/roles.rb', line 108

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:


126
127
128
129
130
131
132
133
134
135
# File 'lib/auth0/api/v2/roles.rb', line 126

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.

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

Raises:

See Also:


91
92
93
94
95
96
97
98
99
100
# File 'lib/auth0/api/v2/roles.rb', line 91

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),
    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:


156
157
158
159
160
161
# File 'lib/auth0/api/v2/roles.rb', line 156

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