descope 1.1.0 → 1.2.0

data/lib/descope/api/v1/management/group.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Descope
+  module Api
+    module V1
+      module Management
+        # Management API calls for SSO groups querying
+        module Group
+          include Descope::Api::V1::Management::Common
+
+          def load_all_groups(tenant_id:)
+            # Load all groups for a given tenant id.
+            mgmt_post(GROUP_LOAD_ALL_PATH, { tenantId: tenant_id })
+          end
+
+          def load_all_groups_for_members(tenant_id:, user_ids: nil, login_ids: nil)
+            # Load all groups for the given user's or login IDs (can be given either).
+            mgmt_post(
+              GROUP_LOAD_ALL_FOR_MEMBER_PATH,
+              {
+                tenantId: tenant_id,
+                loginIds: login_ids,
+                userIds: user_ids
+              }
+            )
+          end
+
+          def load_all_group_members(tenant_id:, group_id:)
+            # Load all members of the given group id.
+            mgmt_post(
+              GROUP_LOAD_ALL_GROUP_MEMBERS_PATH,
+              {
+                tenantId: tenant_id,
+                groupId: group_id
+              }
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/descope/api/v1/management/jwt_template.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Descope
+  module Api
+    module V1
+      module Management
+        # Management API calls for JWT templates
+        module JWTTemplate
+          include Descope::Api::V1::Management::Common
+
+          def create_jwt_template(template: nil)
+            # Create a new JWT template.
+            # Args:
+            # template (dict): the JWT template dict with format
+            #       {
+            #           "name": "name-of-template",
+            #           "description": "description of the template",
+            #           "template": "the template body",
+            #           "conformanceIssuer": True|False,
+            #           "authSchema": "one of default|tenantOnly|none"
+            #       }
+            mgmt_post(JWT_TEMPLATE_CREATE_PATH, { template: })
+          end
+
+          def update_jwt_template(template: nil)
+            # Update an existing JWT template.
+            # The given template must include an "id" field.
+            mgmt_post(JWT_TEMPLATE_UPDATE_PATH, { template: })
+          end
+
+          def delete_jwt_template(id: nil)
+            # Delete the JWT template with the given id.
+            mgmt_post(JWT_TEMPLATE_DELETE_PATH, { id: })
+          end
+
+          def list_jwt_templates
+            # Load all JWT templates for the project.
+            mgmt_post(JWT_TEMPLATE_LIST_PATH, {})
+          end
+
+          def load_jwt_template(id: nil)
+            # Load the JWT template with the given id.
+            mgmt_post(JWT_TEMPLATE_LOAD_PATH, { id: })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/descope/api/v1/management/lists.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Descope
+  module Api
+    module V1
+      module Management
+        # Management API calls for the deny/allow lists (of IPs and texts)
+        module Lists
+          include Descope::Api::V1::Management::Common
+
+          def create_list(name: nil, type: nil, description: nil, data: nil)
+            # Create a new list with the given name and type.
+            body = { name:, type: }
+            body[:description] = description unless description.nil?
+            body[:data] = data unless data.nil?
+            mgmt_post(LIST_CREATE_PATH, body)
+          end
+
+          def update_list(id: nil, name: nil, type: nil, description: nil, data: nil)
+            # Update an existing list. IMPORTANT: All parameters are used as overrides to the existing list.
+            body = { id:, name:, type: }
+            body[:description] = description unless description.nil?
+            body[:data] = data unless data.nil?
+            mgmt_post(LIST_UPDATE_PATH, body)
+          end
+
+          def delete_list(id: nil)
+            # Delete an existing list. IMPORTANT: This action is irreversible. Use carefully.
+            mgmt_post(LIST_DELETE_PATH, { id: })
+          end
+
+          def load_list(id: nil)
+            # Load list by id.
+            mgmt_get("#{LIST_LOAD_PATH}/#{id}")
+          end
+
+          def load_list_by_name(name: nil)
+            # Load list by name.
+            mgmt_get("#{LIST_LOAD_BY_NAME_PATH}/#{name}")
+          end
+
+          def load_all_lists
+            # Load all lists.
+            mgmt_get(LIST_LOAD_ALL_PATH)
+          end
+
+          def import_lists(lists: nil)
+            # Import the given lists.
+            mgmt_post(LIST_IMPORT_PATH, { lists: })
+          end
+
+          def list_add_ips(id: nil, ips: nil)
+            # Add the given IPs to the list with the given id.
+            mgmt_post(LIST_ADD_IPS_PATH, { id:, ips: })
+          end
+
+          def list_remove_ips(id: nil, ips: nil)
+            # Remove the given IPs from the list with the given id.
+            mgmt_post(LIST_REMOVE_IPS_PATH, { id:, ips: })
+          end
+
+          def list_check_ip(id: nil, ip: nil)
+            # Check whether the given IP exists in the list with the given id.
+            mgmt_post(LIST_CHECK_IP_PATH, { id:, ip: })
+          end
+
+          def list_add_texts(id: nil, texts: nil)
+            # Add the given texts to the list with the given id.
+            mgmt_post(LIST_ADD_TEXTS_PATH, { id:, texts: })
+          end
+
+          def list_remove_texts(id: nil, texts: nil)
+            # Remove the given texts from the list with the given id.
+            mgmt_post(LIST_REMOVE_TEXTS_PATH, { id:, texts: })
+          end
+
+          def list_check_text(id: nil, text: nil)
+            # Check whether the given text exists in the list with the given id.
+            mgmt_post(LIST_CHECK_TEXT_PATH, { id:, text: })
+          end
+
+          def list_check_texts(id: nil, texts: nil, match_all: false)
+            # Check whether the given texts exist in the list with the given id (up to 100 texts).
+            # By default it is enough for any of the texts to exist; set match_all to require all of them.
+            mgmt_post(LIST_CHECK_TEXT_PATH, { id:, texts:, matchAll: match_all })
+          end
+
+          def clear_list(id: nil)
+            # Clear all entries from the list with the given id.
+            mgmt_post(LIST_CLEAR_PATH, { id: })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/descope/api/v1/management/management_key.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Descope
+  module Api
+    module V1
+      module Management
+        # Management API calls for management keys
+        module ManagementKey
+          include Descope::Api::V1::Management::Common
+
+          def create_management_key(name:, description: nil, expires_in: 0, permitted_ips: nil, re_bac: nil)
+            # Create a new management key.
+            mgmt_put(MGMT_KEY_CREATE_PATH, {
+                  name:,
+                  description:,
+                  expiresIn: expires_in,
+                  permittedIps: permitted_ips,
+                  reBac: re_bac
+                })
+          end
+
+          def update_management_key(id:, name:, description: nil, permitted_ips: nil, status: nil)
+            # Update an existing management key.
+            mgmt_patch(MGMT_KEY_UPDATE_PATH, {
+                    id:,
+                    name:,
+                    description:,
+                    permittedIps: permitted_ips,
+                    status:
+                  })
+          end
+
+          def get_management_key(id:)
+            # Load an existing management key.
+            mgmt_get(MGMT_KEY_GET_PATH, { id: })
+          end
+
+          def delete_management_key(id:)
+            # Delete an existing management key.
+            mgmt_post(MGMT_KEY_DELETE_PATH, { ids: [id] })
+          end
+
+          def search_management_keys(tenant_ids: nil, status: nil)
+            # Search all management keys.
+            mgmt_get(MGMT_KEY_SEARCH_PATH, {
+                  tenantIds: tenant_ids,
+                  status:
+                })
+          end
+        end
+      end
+    end
+  end
+end

data/lib/descope/api/v1/management/outbound_app.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Descope
+  module Api
+    module V1
+      module Management
+        # Outbound App Management API calls
+        # Manage outbound application tokens for users
+        # @see https://docs.descope.com/api/management/outbound-apps/
+        module OutboundApp
+          include Descope::Mixins::Validation
+          include Descope::Api::V1::Management::Common
+
+          # Outbound App paths
+          OUTBOUND_APP_FETCH_USER_TOKEN_PATH = '/v1/mgmt/outbound/app/user/token'
+          OUTBOUND_APP_DELETE_USER_TOKENS_PATH = '/v1/mgmt/outbound/user/tokens'
+          OUTBOUND_APP_DELETE_TOKEN_BY_ID_PATH = '/v1/mgmt/outbound/token'
+
+          # Fetch outbound application user token with the specified scopes.
+          # @see https://docs.descope.com/api/management/outbound-apps/fetch-outbound-app-user-token
+          #
+          # @param app_id [String] The outbound application ID
+          # @param user_id [String] The user ID to fetch the token for
+          # @param scopes [Array<String>] Optional list of scopes for the token
+          # @param with_refresh_token [Boolean] Optional flag to include refresh token (default: false)
+          # @param force_refresh [Boolean] Optional flag to force token refresh (default: false)
+          # @param tenant_id [String] Optional tenant ID
+          #
+          # @return [Hash] Token information including accessToken, accessTokenExpiry, etc.
+          def fetch_outbound_app_user_token(app_id:, user_id:, scopes: nil, with_refresh_token: false, force_refresh: false, tenant_id: nil)
+            validate_app_id(app_id)
+            validate_user_id(user_id)
+
+            body = {
+              appId: app_id,
+              userId: user_id
+            }
+
+            body[:scopes] = scopes if scopes.is_a?(Array) && !scopes.empty?
+            body[:tenantId] = tenant_id unless tenant_id.nil? || tenant_id.empty?
+
+            # Only include options if at least one is true
+            if with_refresh_token || force_refresh
+              body[:options] = {
+                withRefreshToken: with_refresh_token,
+                forceRefresh: force_refresh
+              }
+            end
+
+            mgmt_post(OUTBOUND_APP_FETCH_USER_TOKEN_PATH, body)
+          end
+
+          # Delete outbound application tokens by appId or userId.
+          # At least one of app_id or user_id must be provided.
+          # @see https://docs.descope.com/api/management/outbound-apps/delete-outbound-app-user-tokens
+          #
+          # @param app_id [String] Optional outbound application ID
+          # @param user_id [String] Optional user ID
+          #
+          # @return [void]
+          def delete_outbound_app_user_tokens(app_id: nil, user_id: nil)
+            if (app_id.nil? || app_id.empty?) && (user_id.nil? || user_id.empty?)
+              raise Descope::ArgumentException.new(
+                'At least one of app_id or user_id must be provided',
+                code: 400
+              )
+            end
+
+            query_params = {}
+            query_params[:appId] = app_id unless app_id.nil? || app_id.empty?
+            query_params[:userId] = user_id unless user_id.nil? || user_id.empty?
+
+            mgmt_delete(OUTBOUND_APP_DELETE_USER_TOKENS_PATH, query_params)
+          end
+
+          # Delete outbound application token by its ID.
+          # @see https://docs.descope.com/api/management/outbound-apps/delete-outbound-app-token-by-id
+          #
+          # @param token_id [String] The token ID to delete
+          #
+          # @return [void]
+          def delete_outbound_app_token_by_id(token_id:)
+            validate_token_id(token_id)
+
+            query_params = { id: token_id }
+            mgmt_delete(OUTBOUND_APP_DELETE_TOKEN_BY_ID_PATH, query_params)
+          end
+
+          private
+
+          def validate_app_id(app_id)
+            return unless app_id.nil? || app_id.empty?
+
+            raise Descope::ArgumentException.new(
+              'app_id cannot be empty',
+              code: 400
+            )
+          end
+
+          def validate_token_id(token_id)
+            return unless token_id.nil? || token_id.empty?
+
+            raise Descope::ArgumentException.new(
+              'token_id cannot be empty',
+              code: 400
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/descope/api/v1/management/password.rb

@@ -10,7 +10,7 @@ module Descope
 
           def get_password_settings(tenant_id)
             # Get password settings for the provided tenant id.
-            get(PASSWORD_SETTINGS_PATH, { tenantId: tenant_id })
+            mgmt_get(PASSWORD_SETTINGS_PATH, { tenantId: tenant_id })
           end
 
           def update_password_settings(settings)
@@ -20,7 +20,7 @@ module Descope
 
             # Update password settings for the provided tenant id.
             body = compose_settings_body(settings)
-            post(PASSWORD_SETTINGS_PATH, body)
+            mgmt_post(PASSWORD_SETTINGS_PATH, body)
           end
 
           private

data/lib/descope/api/v1/management/permission.rb

@@ -17,7 +17,7 @@ module Descope
               name:,
               description:
             }
-            post(PERMISSION_CREATE_PATH, request_params)
+            mgmt_post(PERMISSION_CREATE_PATH, request_params)
           end
 
           def update_permission(name: nil, new_name: nil, description: nil)
@@ -29,17 +29,17 @@ module Descope
               newName: new_name,
               description:
             }
-            post(PERMISSION_UPDATE_PATH, request_params)
+            mgmt_post(PERMISSION_UPDATE_PATH, request_params)
           end
 
           def delete_permission(name = nil)
             # Delete an existing permission. IMPORTANT: This action is irreversible. Use carefully.
-            post(PERMISSION_DELETE_PATH, { name: })
+            mgmt_post(PERMISSION_DELETE_PATH, { name: })
           end
 
           def load_all_permissions
             # Load all permissions.
-            get(PERMISSION_LOAD_ALL_PATH)
+            mgmt_get(PERMISSION_LOAD_ALL_PATH)
           end
         end
       end

data/lib/descope/api/v1/management/project.rb

@@ -10,7 +10,7 @@ module Descope
 
           def rename_project(name)
             # Rename a project.
-            post(PROJECT_UPDATE_NAME, { name: })
+            mgmt_post(PROJECT_UPDATE_NAME, { name: })
           end
 
           def export_project
@@ -20,7 +20,7 @@ module Descope
             #    - Users, tenants and access keys are not cloned.
             #    - Secrets, keys and tokens are not stripped from the exported data.
             #   @returns a HASH containing the exported JSON files payload.
-            post(PROJECT_EXPORT_PATH)
+            mgmt_post(PROJECT_EXPORT_PATH)
           end
 
           def import_project(files: nil, excludes: nil)
@@ -28,12 +28,12 @@ module Descope
             # The argument of files should be the output of the export project endpoint
             body = { files: }
             body[:excludes] = excludes unless excludes.nil?
-            post(PROJECT_IMPORT_PATH, body)
+            mgmt_post(PROJECT_IMPORT_PATH, body)
           end
 
           def delete_project
             # Delete the current project. IMPORTANT: This action is irreversible. Use carefully.
-            post(PROJECT_DELETE_PATH)
+            mgmt_post(PROJECT_DELETE_PATH)
           end
 
           def clone_project(name: nil, tag: nil)
@@ -44,7 +44,7 @@ module Descope
               name:,
               tag:
             }
-            post(PROJECT_CLONE, request_params)
+            mgmt_post(PROJECT_CLONE, request_params)
           end
         end
       end

data/lib/descope/api/v1/management/role.rb

@@ -17,7 +17,7 @@ module Descope
               permissionNames: permission_names,
               tenantId: tenant_id
             }
-            post(ROLE_CREATE_PATH, request_params)
+            mgmt_post(ROLE_CREATE_PATH, request_params)
           end
 
           def update_role(name: nil, new_name: nil, description: nil, permission_names: nil, tenant_id: nil)
@@ -31,7 +31,7 @@ module Descope
               permissionNames: permission_names,
               tenantId: tenant_id
             }
-            post(ROLE_UPDATE_PATH, request_params)
+            mgmt_post(ROLE_UPDATE_PATH, request_params)
           end
 
           def delete_role(name: nil, tenant_id: nil)
@@ -40,12 +40,12 @@ module Descope
 
             request_params = { name: }
             request_params[:tenantId] = tenant_id if tenant_id
-            post(ROLE_DELETE_PATH, request_params)
+            mgmt_post(ROLE_DELETE_PATH, request_params)
           end
 
           def load_all_roles
             # Load all roles.
-            get(ROLE_LOAD_ALL_PATH)
+            mgmt_get(ROLE_LOAD_ALL_PATH)
           end
 
           def search_roles(role_names: nil, tenant_ids: nil, role_name_like: nil, permission_names: nil)
@@ -55,7 +55,7 @@ module Descope
             request_params[:tenantIds] = tenant_ids if tenant_ids
             request_params[:roleNameLike] = role_name_like if role_name_like
             request_params[:permissionNames] = permission_names if permission_names
-            post(ROLE_SEARCH_PATH, request_params)
+            mgmt_post(ROLE_SEARCH_PATH, request_params)
           end
         end
       end

data/lib/descope/api/v1/management/scim.rb

@@ -11,21 +11,21 @@ module Descope
           def scim_search_groups(filter: nil, start_index: nil, count: nil, excluded_attributes: nil)
             # Search SCIM Groups
             url = compose_scim_search_groups_url(filter, start_index, count, excluded_attributes)
-            get(url)
+            mgmt_get(url)
           end
 
           def scim_create_group(group_id: nil, display_name: nil, members: nil, external_id: nil,
                                 excluded_attributes: nil)
             # Create SCIM Group
             body = compose_scim_create_group_body(group_id, display_name, members, external_id, excluded_attributes)
-            post(SCIM_GROUPS_PATH, body)
+            mgmt_post(SCIM_GROUPS_PATH, body)
           end
 
           def scim_load_group(group_id: nil, display_name: nil, external_id: nil, excluded_attributes: nil)
             # Load SCIM Group, using a valid access key.
             validate_scim_group_id(group_id)
             url = compose_scim_create_group_url(group_id, display_name, external_id, excluded_attributes)
-            get(url)
+            mgmt_get(url)
           end
 
           def scim_update_group(group_id: nil, display_name: nil, members: nil, external_id: nil,
@@ -33,38 +33,38 @@ module Descope
             # Update SCIM Group, using a valid access key.
             validate_scim_group_id(group_id)
             body = compose_scim_update_group_body(group_id, display_name, members, external_id, excluded_attributes)
-            patch("#{SCIM_GROUPS_PATH}/#{group_id}", body)
+            mgmt_patch("#{SCIM_GROUPS_PATH}/#{group_id}", body)
           end
 
           def scim_delete_group(group_id)
             # Delete SCIM Group, using a valid access key.
             validate_scim_group_id(group_id)
             url = "#{SCIM_GROUPS_PATH}/#{group_id}"
-            delete(url)
+            mgmt_delete(url)
           end
 
           def scim_patch_group(group_id: nil, user_id: nil, operations: nil)
             # Patch SCIM Group, using a valid access key.
             validate_scim_group_id(group_id)
             url = compose_scim_patch_group_url(group_id, user_id, operations)
-            patch(url)
+            mgmt_patch(url)
           end
 
           # SCIM Users
           def scim_load_resource_types
             # Load SCIM Resource Types, using a valid access key.
-            get(SCIM_RESOURCE_TYPES_PATH)
+            mgmt_get(SCIM_RESOURCE_TYPES_PATH)
           end
 
           def scim_load_service_provider_config
             # Load SCIM Service Provider Config, using a valid access key.
-            get(SCIM_SERVICE_PROVIDER_CONFIG_PATH)
+            mgmt_get(SCIM_SERVICE_PROVIDER_CONFIG_PATH)
           end
 
           def scim_search_users(filter: nil, start_index: nil, count: nil)
             # Search SCIM Users, using a valid access key.
             url = compose_scim_search_users_url(filter, start_index, count)
-            get(url)
+            mgmt_get(url)
           end
 
           def scim_create_user(user_id: nil, display_name: nil, emails: nil,
@@ -72,28 +72,28 @@ module Descope
             # Create SCIM User, using a valid access key.
             validate_user_id(user_id)
             body = compose_scim_create_user_body(user_id, display_name, emails, phone_numbers, active, name, user_name)
-            post(SCIM_USERS_PATH, body)
+            mgmt_post(SCIM_USERS_PATH, body)
           end
 
           def scim_load_user(user_id)
             # Load SCIM User, using a valid access key.
             validate_user_id(user_id)
             url = "#{SCIM_USERS_PATH}/#{user_id}"
-            get(url)
+            mgmt_get(url)
           end
 
           def scim_update_user(user_id)
             # Update SCIM User, using a valid access key.
             validate_user_id(user_id)
             url = "#{SCIM_USERS_PATH}/#{user_id}"
-            patch(url)
+            mgmt_patch(url)
           end
 
           def scim_delete_user(user_id)
             # Delete SCIM User, using a valid access key.
             validate_user_id(user_id)
             url = "#{SCIM_USERS_PATH}/#{user_id}"
-            delete(url)
+            mgmt_delete(url)
           end
 
           def scim_patch_user(user_id: nil, group_id: nil, operations: nil)
@@ -101,7 +101,7 @@ module Descope
             validate_user_id(user_id)
             validate_scim_group_id(group_id)
             body = compose_scim_patch_user_body(user_id, group_id, operations)
-            patch(SCIM_USERS_PATH, body)
+            mgmt_patch(SCIM_USERS_PATH, body)
           end
 
           private

data/lib/descope/api/v1/management/scope_claim_mapping.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Descope
+  module Api
+    module V1
+      module Management
+        # Manage project-wide OIDC scope-to-claim mapping
+        module ScopeClaimMapping
+          include Descope::Api::V1::Management::Common
+
+          def get_scope_claim_mapping # rubocop:disable Naming/AccessorMethodName
+            # Get the project-wide OIDC scope-to-claim mappings.
+            mgmt_post(SCOPE_CLAIM_MAPPING_GET_PATH)
+          end
+
+          def set_scope_claim_mapping(mappings: nil)
+            # Set the project-wide OIDC scope-to-claim mappings.
+            # mappings (Array[]): the scope-to-claim mappings to set. Each in the following format:
+            #   {
+            #       "scope": "name of the OIDC scope",
+            #       "claims": ["list of claims mapped to the scope"]
+            #   }
+            mgmt_post(SCOPE_CLAIM_MAPPING_SET_PATH, { mappings: })
+          end
+
+          def delete_scope_claim_mapping
+            # Delete the project-wide OIDC scope-to-claim mappings.
+            mgmt_post(SCOPE_CLAIM_MAPPING_DELETE_PATH)
+          end
+        end
+      end
+    end
+  end
+end