instructure/canvas-lms · error · Lti::SubscriptionsValidator::MissingCapability

Missing required capability

Error message

Missing required capability

What it means

Raised by Lti::SubscriptionsValidator#check_required_capabilities! when the tool proxy has not been granted (enabled_capabilities) any of the capabilities required for a requested subscription event type. Even a valid event type needs a corresponding granted capability (e.g. .* subscription scopes) unless the tool holds the grant-all capability.

Solutions

1. Edit the tool proxy / developer key to enable the required capabilities for the event type
2. Grant the webhook grant-all capability if appropriate for the trust relationship
3. Reduce EventTypes to only events whose capabilities the tool already has
4. Re-approve the tool with the additional requested capabilities

Example fix

// before
tool_proxy.enabled_capabilities = [] # cannot subscribe
tool_proxy.enabled_capabilities = ['url', 'WebhookSubscription.event_type.subscription_created']
# after
tool_proxy.enabled_capabilities = ['url', 'WebhookSubscription.event_type.subscription_created']

caps = ToolConsumerProfile.webhook_subscription_capabilities
missing = event_types.flat_map { |e| caps[e.to_sym] || [] } - tool_proxy.enabled_capabilities.to_a

begin
  validator.validate_subscription_request!
rescue Lti::SubscriptionsValidator::MissingCapability
  request_capability_grant(event_types) # re-approve tool with required capabilities
end

When it happens

Trigger: Creating a LiveEvents subscription where EventTypes is valid but tool_proxy.enabled_capabilities does not intersect the required capabilities for that event type; tool approved without the needed webhook scopes.

Common situations: Developer installs a tool without checking the required capability checkboxes during tool approval; account admin grants the subscription feature flag but not the capability; new event type added to subscription requires capabilities the tool never had.

Understand the failure class

Background: "You do not have permission" / 403 Forbidden errors: authenticated but not allowed — causes and fixes across open-source libraries — this error's family across 31 libraries.

Related errors

• Tool does not have access to requested context
• EventType # is invalid
• Access token expired
• Access token invalid - signature likely incorrect
• ActiveRecord::RecordNotFound

AI-assisted analysis of instructure/canvas-lms@1c9f0bb801 (2026-09-15). Data as JSON: /api/errors/5d8a6ce72d57b049. Report an issue: GitHub.

Appendix: source

Thrown at app/controllers/lti/subscriptions_validator.rb:53

      "root_account" => Account,
      "assignment" => Assignment
    }.freeze

    attr_reader :subscription, :tool_proxy

    def initialize(subscription, tool_proxy)
      @subscription = subscription.with_indifferent_access
      @tool_proxy = tool_proxy
    end

    def check_required_capabilities!
      capabilities_hash = ToolConsumerProfile.webhook_subscription_capabilities
      return if tool_proxy.enabled_capabilities.include?(ToolConsumerProfile.webhook_grant_all_capability)

      subscription[:EventTypes].each do |event_type|
        raise MissingCapability, "EventType #{event_type} is invalid" unless capabilities_hash.key?(event_type.to_sym)
        unless tool_proxy.enabled_capabilities.intersect?(capabilities_hash[event_type.to_sym])
          raise MissingCapability, "Missing required capability"
        end
      end
    end

    def check_tool_context!
      requested_context = subscription_context
      requested_context = requested_context.course if requested_context.respond_to?(:course)
      raise ToolNotInContext, "Tool does not have access to requested context" unless tool_proxy.active_in_context?(requested_context)
    end

    def validate_subscription_request!
      check_required_capabilities!
      check_tool_context!
    end

    def self.validate_subscription_context!(subscription)
      raise ContextNotFound unless retrieve_context(subscription).present?

View on GitHub (pinned to 1c9f0bb801)