descope 1.0.7 → 1.2.0

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

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

@@ -18,7 +18,7 @@ module Descope
             body[:enabled] = enabled if enabled
             body[:logo] = logo if logo
             body[:loginPageUrl] = login_page_url if login_page_url
-            post(SSO_APPLICATION_OIDC_CREATE_PATH, body)
+            mgmt_post(SSO_APPLICATION_OIDC_CREATE_PATH, body)
           end
 
           # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
@@ -78,14 +78,14 @@ module Descope
               force_authentication:,
               logout_redirect_url:
             )
-            post(SSO_APPLICATION_SAML_CREATE_PATH, body)
+            mgmt_post(SSO_APPLICATION_SAML_CREATE_PATH, body)
           end
 
           def update_sso_oidc_app(id: nil, name: nil, description: nil, enabled: nil, logo: nil, login_page_url: nil, force_authentication: nil)
             # Update an existing OIDC sso application with the given parameters. IMPORTANT: All parameters are used as overrides
             # to the existing sso application. Empty fields will override populated fields. Use carefully.
             body = compose_create_update_oidc_body(name, login_page_url, id, description, enabled, logo, force_authentication)
-            post(SSO_APPLICATION_OIDC_UPDATE_PATH, body)
+            mgmt_post(SSO_APPLICATION_OIDC_UPDATE_PATH, body)
           end
 
           def update_saml_application(
@@ -143,17 +143,17 @@ module Descope
               force_authentication:,
               logout_redirect_url:
             )
-            post(SSO_APPLICATION_SAML_UPDATE_PATH, body)
+            mgmt_post(SSO_APPLICATION_SAML_UPDATE_PATH, body)
           end
 
           def delete_sso_app(id)
             # Delete an existing sso application. IMPORTANT: This operation is irreversible. Use carefully.
-            delete(SSO_APPLICATION_DELETE_PATH, { id: })
+            mgmt_delete(SSO_APPLICATION_DELETE_PATH, { id: })
           end
 
           def load_sso_app(id)
             # Load an existing sso application.
-            get(SSO_APPLICATION_LOAD_PATH, { id: })
+            mgmt_get(SSO_APPLICATION_LOAD_PATH, { id: })
           end
 
           def load_all_sso_apps
@@ -167,7 +167,7 @@ module Descope
             #           ]
             #       }
             #   Containing the loaded sso applications information.
-            get(SSO_APPLICATION_LOAD_ALL_PATH, {})
+            mgmt_get(SSO_APPLICATION_LOAD_ALL_PATH, {})
           end
 
           private

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

@@ -10,12 +10,12 @@ module Descope
 
           def get_sso_settings(tenant_id)
             # Get SSO settings for the provided tenant id.
-            get(SSO_SETTINGS_PATH, { tenantId: tenant_id })
+            mgmt_get(SSO_SETTINGS_PATH, { tenantId: tenant_id })
           end
 
           def delete_sso_settings(tenant_id)
             # Delete SSO settings for the provided tenant id.
-            delete(SSO_SETTINGS_PATH, { tenantId: tenant_id })
+            mgmt_delete(SSO_SETTINGS_PATH, { tenantId: tenant_id })
           end
 
           def configure_sso_oidc(tenant_id: nil, settings: nil, redirect_url: nil, domain: nil)
@@ -28,7 +28,7 @@ module Descope
               redirectUrl: redirect_url,
               domain:
             }
-            post(SSO_OIDC_PATH, request_params)
+            mgmt_post(SSO_OIDC_PATH, request_params)
           end
 
           def configure_sso_saml(tenant_id: nil, settings: nil, redirect_url: nil, domain: nil)
@@ -41,12 +41,12 @@ module Descope
               redirectUrl: redirect_url,
               domain:
             }
-            post(SSO_SETTINGS_PATH, request_params)
+            mgmt_post(SSO_SETTINGS_PATH, request_params)
           end
 
           def configure_sso_saml_metadata(tenant_id: nil, settings: nil, redirect_url: nil, domain: nil)
             # Configure tenant SSO SAML Metadata, using a valid management key.
-            post(SSO_METADATA_PATH, compose_metadata_body(tenant_id, settings, redirect_url, domain))
+            mgmt_post(SSO_METADATA_PATH, compose_metadata_body(tenant_id, settings, redirect_url, domain))
           end
 
           private

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

@@ -17,7 +17,8 @@ module Descope
 
             self_provisioning_domains ||= []
             custom_attributes ||= {}
-            post(TENANT_CREATE_PATH, compose_tenant_create_update_body(name, id, self_provisioning_domains, custom_attributes))
+            mgmt_post(TENANT_CREATE_PATH,
+                      compose_tenant_create_update_body(name, id, self_provisioning_domains, custom_attributes))
           end
 
           def update_tenant(name: nil, id: nil, self_provisioning_domains: nil, custom_attributes: nil)
@@ -26,22 +27,23 @@ module Descope
             # @see https://docs.descope.com/api/openapi/tenantmanagement/operation/UpdateTenant/
             self_provisioning_domains ||= []
             custom_attributes ||= {}
-            post(TENANT_UPDATE_PATH, compose_tenant_create_update_body(name, id, self_provisioning_domains, custom_attributes))
+            mgmt_post(TENANT_UPDATE_PATH,
+                      compose_tenant_create_update_body(name, id, self_provisioning_domains, custom_attributes))
           end
 
           def delete_tenant(id = nil)
             # Delete an existing tenant. IMPORTANT: This action is irreversible. Use carefully.
-            post(TENANT_DELETE_PATH, { id: })
+            mgmt_post(TENANT_DELETE_PATH, { id: })
           end
 
           def load_tenant(id = nil)
             # Load tenant by id.
-            get(TENANT_LOAD_PATH, { id: })
+            mgmt_get(TENANT_LOAD_PATH, { id: })
           end
 
           def load_all_tenants
             # Load all tenants.
-            get(TENANT_LOAD_ALL_PATH)
+            mgmt_get(TENANT_LOAD_ALL_PATH)
           end
 
           def search_all_tenants(ids: nil, names: nil, self_provisioning_domains: nil, custom_attributes: nil)
@@ -52,7 +54,7 @@ module Descope
               selfProvisioningDomains: self_provisioning_domains,
               customAttributes: custom_attributes
             }
-            post(TENANT_SEARCH_ALL_PATH, request_params)
+            mgmt_post(TENANT_SEARCH_ALL_PATH, request_params)
           end
 
           private