end_point_blank 0.12.0 → 0.13.0

data/lib/end_point_blank/management/error.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "error_codes"
+
+module EndPointBlank
+  # Reopened with the same superclass in end_point_blank.rb; declared here too
+  # so this file can be required on its own.
+  class Error < StandardError; end
+
+  module Management
+    # Raised by {Client} for every refused or failed management API call.
+    #
+    # The API answers errors as
+    # <tt>{"error": {"code", "message", "details"}}</tt>. +code+ is stable and
+    # meant for programs; match on it (see {ErrorCodes}). +message+ is for
+    # people. +details+ is present only when there is something field-level to
+    # say, e.g. a +validation_failed+ error's fields.
+    #
+    # A code this SDK does not know still raises, carrying that code. An answer
+    # that is not the API's error shape (an HTML page from a proxy) raises with
+    # code +http_error+; a request that never got an answer raises with code
+    # +connection_error+ and no status.
+    class Error < EndPointBlank::Error
+      # @return [String] the API's error code, or one of {ErrorCodes::SDK}
+      attr_reader :code
+      # @return [Object, nil] field-level details, as the API sent them
+      attr_reader :details
+      # @return [Integer, nil] the HTTP status; nil for +connection_error+
+      attr_reader :status
+      # @return [Numeric, nil] the Retry-After header's seconds, when present
+      attr_reader :retry_after
+      # @return [String, nil] the Location header, e.g. on +idempotency_replay_unavailable+
+      attr_reader :location
+      # @return [String, nil] the X-Request-Id header, for support requests
+      attr_reader :request_id
+      # @return [String, nil] the HTTP method of the failed request
+      attr_reader :http_method
+      # @return [String, nil] the path of the failed request (no query, no host)
+      attr_reader :path
+
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(message, code:, status: nil, details: nil, retry_after: nil, location: nil,
+                     request_id: nil, http_method: nil, path: nil)
+        @code = code
+        @status = status
+        @details = details
+        @retry_after = retry_after
+        @location = location
+        @request_id = request_id
+        @http_method = http_method
+        @path = path
+        super(message)
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # Builds the error for an answer outside 2xx. +headers+ is any Hash-like
+      # whose keys are header names in any case.
+      def self.from_response(status:, headers:, body:, http_method: nil, path: nil)
+        code, message, details = parse_body(status, body)
+        if code == ErrorCodes::IDEMPOTENCY_REPLAY_UNAVAILABLE
+          message = replay_unavailable_message(header(headers, "location"))
+        end
+
+        new(message,
+            code: code, status: status, details: details,
+            retry_after: parse_retry_after(header(headers, "retry-after")),
+            location: header(headers, "location"), request_id: header(headers, "x-request-id"),
+            http_method: http_method, path: path)
+      end
+
+      # Whether this error is +code+ (a String or Symbol).
+      def code?(code)
+        self.code == code.to_s
+      end
+
+      def inspect
+        "#<#{self.class.name} code=#{code.inspect} status=#{status.inspect} message=#{message.inspect}>"
+      end
+
+      class << self
+        # The case-insensitive value of header +name+, or nil.
+        def header(headers, name)
+          return nil if headers.nil?
+
+          headers.each { |key, value| return value.to_s if key.to_s.casecmp?(name) }
+          nil
+        end
+
+        # Seconds to wait from a Retry-After header: delta-seconds, or an
+        # HTTP-date. nil when absent or unreadable; never negative.
+        def parse_retry_after(value)
+          return nil if value.nil? || value.strip.empty?
+          return Integer(value.strip, 10) if value.strip.match?(/\A\d+\z/)
+
+          require "time"
+          [Time.httpdate(value.strip) - Time.now, 0].max
+        rescue ArgumentError
+          nil
+        end
+
+        private
+
+        def parse_body(status, body)
+          error = JSON.parse(body.to_s)["error"]
+          if error.is_a?(Hash) && error["code"].is_a?(String)
+            message = error["message"].is_a?(String) ? error["message"] : "The request failed (#{error["code"]})."
+            return [error["code"], message, error["details"]]
+          end
+
+          unexpected(status, body)
+        rescue JSON::ParserError, TypeError, NoMethodError
+          unexpected(status, body)
+        end
+
+        def unexpected(status, body)
+          snippet = body.to_s.strip.gsub(/\s+/, " ")[0, 200]
+          message = "The management API answered HTTP #{status} without its JSON error shape"
+          message += snippet.empty? ? "." : ": #{snippet}"
+          [ErrorCodes::HTTP_ERROR, message, nil]
+        end
+
+        def replay_unavailable_message(location)
+          message = +"A request with this Idempotency-Key already succeeded, and its answer held a secret " \
+                     "that is shown only once, so it can't be replayed and was not retried. Read or list " \
+                     "the resource to see its current state"
+          message << " (#{location})" if location
+          message << ". If you need a secret you never received, rotate the credential."
+          message
+        end
+      end
+    end
+  end
+end

data/lib/end_point_blank/management/error_codes.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module EndPointBlank
+  module Management
+    # Every +error.code+ the management API can answer, with its HTTP status, as
+    # app_portal's docs list them, plus the few codes this SDK raises itself
+    # when there is no API answer to read one from.
+    #
+    # Match on these rather than on messages, which are for people and may
+    # change. The list is not closed: an {Error} carrying a code missing here
+    # still raises with that code, so a newer API never breaks an older SDK.
+    module ErrorCodes
+      # Authentication and limits
+      MISSING_KEY = "missing_key"
+      INVALID_KEY = "invalid_key"
+      RUNTIME_CREDENTIAL_REFUSED = "runtime_credential_refused"
+      INSUFFICIENT_SCOPE = "insufficient_scope"
+      AUDIT_UNAVAILABLE = "audit_unavailable"
+      RATE_LIMITED = "rate_limited"
+      PLAN_LIMIT = "plan_limit"
+
+      # Requests
+      VALIDATION_FAILED = "validation_failed"
+      # No such resource in your organization (another organization's id
+      # answers this too), or no such /api/v1 path.
+      NOT_FOUND = "not_found"
+      INVALID_PAGINATION = "invalid_pagination"
+      INVALID_FILTER = "invalid_filter"
+      INVALID_IDEMPOTENCY_KEY = "invalid_idempotency_key"
+      IDEMPOTENCY_KEY_REUSED = "idempotency_key_reused"
+      IDEMPOTENCY_REQUEST_IN_PROGRESS = "idempotency_request_in_progress"
+      IDEMPOTENCY_REPLAY_UNAVAILABLE = "idempotency_replay_unavailable"
+      # Any request the API cannot read (e.g. a body that is not JSON).
+      BAD_REQUEST = "bad_request"
+      INTERNAL_SERVER_ERROR = "internal_server_error"
+
+      # Applications, environments and API packages
+      HAS_DEPENDENTS = "has_dependents"
+      PROTECTED = "protected"
+      INVALID_ENVIRONMENT_BASE_URLS = "invalid_environment_base_urls"
+      API_PACKAGE_ASSIGNED = "api_package_assigned"
+      INTAKE_SYNC_FAILED = "intake_sync_failed"
+
+      # Credentials
+      DELETE_REFUSED = "delete_refused"
+      INTAKE_CREDENTIAL = "intake_credential"
+      INTAKE_REJECTED = "intake_rejected"
+      INTAKE_UNAVAILABLE = "intake_unavailable"
+
+      # Clients, packages and grants
+      INVALID_CONTACTS = "invalid_contacts"
+      INVALID_PACKAGES = "invalid_packages"
+      INVALID_GRANTS = "invalid_grants"
+      INVALID_MANAGED = "invalid_managed"
+      CLIENT_NOT_ACCEPTED = "client_not_accepted"
+      CLIENT_ACCEPTED = "client_accepted"
+      CLIENT_NOT_MANAGED = "client_not_managed"
+      ALREADY_A_MEMBER = "already_a_member"
+      MANAGED_CLIENT_HAS_CREDENTIALS = "managed_client_has_credentials"
+      API_PACKAGE_NOT_FOUND = "api_package_not_found"
+      ENVIRONMENT_NOT_FOUND = "environment_not_found"
+      ALREADY_ASSIGNED = "already_assigned"
+      NOTHING_PUBLISHED_IN_ENVIRONMENT = "nothing_published_in_environment"
+      APPLICATION_NOT_FOUND = "application_not_found"
+      ENDPOINT_NOT_FOUND = "endpoint_not_found"
+      ENVIRONMENT_NOT_IN_APPLICATION = "environment_not_in_application"
+      ALREADY_GRANTED = "already_granted"
+      GRANT_REVOKED_CONCURRENTLY = "grant_revoked_concurrently"
+
+      # The warning code API package endpoint writes answer in +warnings+ (not
+      # an error): a client assignment of the package now derives no grant.
+      ASSIGNMENT_DERIVES_NOTHING = "assignment_derives_nothing"
+
+      # Raised by this SDK, never sent by the API: the request never got an
+      # answer (DNS, TLS, refused connection, timeout).
+      CONNECTION_ERROR = "connection_error"
+      # Raised by this SDK: an error answer whose body is not the API's JSON
+      # error shape, such as an HTML page from a proxy. +status+ still says
+      # what happened.
+      HTTP_ERROR = "http_error"
+      # Raised by this SDK: a success answer whose body is not JSON.
+      INVALID_RESPONSE = "invalid_response"
+
+      # The HTTP status the API answers each of its codes with.
+      STATUSES = {
+        MISSING_KEY => 401, INVALID_KEY => 401, RUNTIME_CREDENTIAL_REFUSED => 401,
+        INSUFFICIENT_SCOPE => 403, AUDIT_UNAVAILABLE => 503, RATE_LIMITED => 429, PLAN_LIMIT => 402,
+        VALIDATION_FAILED => 422, NOT_FOUND => 404, INVALID_PAGINATION => 400, INVALID_FILTER => 422,
+        INVALID_IDEMPOTENCY_KEY => 400, IDEMPOTENCY_KEY_REUSED => 422,
+        IDEMPOTENCY_REQUEST_IN_PROGRESS => 409, IDEMPOTENCY_REPLAY_UNAVAILABLE => 409,
+        BAD_REQUEST => 400, INTERNAL_SERVER_ERROR => 500,
+        HAS_DEPENDENTS => 422, PROTECTED => 422, INVALID_ENVIRONMENT_BASE_URLS => 422,
+        API_PACKAGE_ASSIGNED => 422, INTAKE_SYNC_FAILED => 422,
+        DELETE_REFUSED => 422, INTAKE_CREDENTIAL => 409, INTAKE_REJECTED => 422, INTAKE_UNAVAILABLE => 503,
+        INVALID_CONTACTS => 422, INVALID_PACKAGES => 422, INVALID_GRANTS => 422, INVALID_MANAGED => 422,
+        CLIENT_NOT_ACCEPTED => 422, CLIENT_ACCEPTED => 422, CLIENT_NOT_MANAGED => 422,
+        ALREADY_A_MEMBER => 422, MANAGED_CLIENT_HAS_CREDENTIALS => 422, API_PACKAGE_NOT_FOUND => 422,
+        ENVIRONMENT_NOT_FOUND => 422, ALREADY_ASSIGNED => 422, NOTHING_PUBLISHED_IN_ENVIRONMENT => 422,
+        APPLICATION_NOT_FOUND => 422, ENDPOINT_NOT_FOUND => 422, ENVIRONMENT_NOT_IN_APPLICATION => 422,
+        ALREADY_GRANTED => 422, GRANT_REVOKED_CONCURRENTLY => 409
+      }.freeze
+
+      # Every code the API can send, as strings.
+      ALL = STATUSES.keys.freeze
+
+      # Codes this SDK raises itself.
+      SDK = [CONNECTION_ERROR, HTTP_ERROR, INVALID_RESPONSE].freeze
+
+      # Whether +code+ is one this version of the SDK knows about.
+      def self.known?(code)
+        STATUSES.key?(code) || SDK.include?(code)
+      end
+    end
+  end
+end

data/lib/end_point_blank/management/idempotency_key.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module EndPointBlank
+  module Management
+    # The Idempotency-Key a management API request carries: every POST has
+    # one, so a retry of it is replayed by the API rather than run twice.
+    module IdempotencyKey
+      MAX_LENGTH = 255
+
+      # The key to send for +method+: the caller's (stripped, as the API reads
+      # it), or a new random UUID v4 for a POST without one; nil for any other
+      # method, which must not be given one.
+      #
+      # @raise [ArgumentError] for a key on a non-POST, or an empty or
+      #   too-long key
+      def self.resolve(method, key)
+        unless method == "POST"
+          raise ArgumentError, "idempotency_key applies to POST requests only" unless key.nil?
+
+          return nil
+        end
+        return SecureRandom.uuid if key.nil?
+
+        key = key.to_s.strip
+        return key if key.length.between?(1, MAX_LENGTH)
+
+        raise ArgumentError, "idempotency_key must be 1 to #{MAX_LENGTH} characters"
+      end
+    end
+  end
+end

data/lib/end_point_blank/management/page.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module EndPointBlank
+  module Management
+    # One page of a management API list: the items (+data+, Hashes with String
+    # keys, as the API sent them) and the cursor for the next page, nil on the
+    # last one. Enumerable over its items.
+    #
+    # Pass +next_cursor+ as +after:+ to the same list call for the next page,
+    # or use the resource's +each+ to walk every page.
+    class Page
+      include Enumerable
+
+      # @return [Array<Hash>]
+      attr_reader :data
+      # @return [String, nil]
+      attr_reader :next_cursor
+
+      def initialize(data:, next_cursor:)
+        @data = data
+        @next_cursor = next_cursor
+      end
+
+      # Builds a page from a list answer, <tt>{"data" => [...], "next_cursor" => ...}</tt>.
+      def self.from_body(body)
+        body = {} unless body.is_a?(Hash)
+        new(data: Array(body["data"]), next_cursor: body["next_cursor"])
+      end
+
+      def each(&block)
+        return enum_for(:each) unless block
+
+        data.each(&block)
+        self
+      end
+
+      # Whether there is a page after this one.
+      def next_page?
+        !next_cursor.nil? && !next_cursor.empty?
+      end
+
+      def size
+        data.size
+      end
+
+      def empty?
+        data.empty?
+      end
+
+      def inspect
+        "#<#{self.class.name} size=#{size} next_cursor=#{next_cursor.inspect}>"
+      end
+    end
+  end
+end

data/lib/end_point_blank/management/resources/api_packages.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module EndPointBlank
+  module Management
+    module Resources
+      # +/api_packages+: your organization's API packages, and what each one
+      # publishes (+/api_packages/:id/endpoints+).
+      #
+      # A package: <tt>{"id", "name", "organization_id", "inserted_at",
+      # "updated_at"}</tt>.
+      class ApiPackages < Base
+        # GET /api_packages. @return [Page]
+        def list(limit: nil, after: nil)
+          list_page(path("api_packages"), limit, after)
+        end
+
+        # Every API package, across pages. @return [Enumerator, nil]
+        def each(limit: nil, &block)
+          each_item(path("api_packages"), limit, &block)
+        end
+
+        # GET /api_packages/:id. @return [Hash]
+        def get(id)
+          get_data(path("api_packages", id))
+        end
+
+        # POST /api_packages. @return [Hash] the new package
+        def create(name:, idempotency_key: nil)
+          post_data(path("api_packages"), { name: name }, idempotency_key)
+        end
+
+        # PATCH /api_packages/:id (rename). @return [Hash]
+        def update(id, name:)
+          patch_data(path("api_packages", id), { name: name })
+        end
+
+        # DELETE /api_packages/:id. Refused with +api_package_assigned+ while
+        # a client holds it. @return [Hash] <tt>{"id", "deleted"}</tt>
+        def delete(id)
+          delete_data(path("api_packages", id))
+        end
+
+        # GET /api_packages/:id/endpoints: what the package publishes, one
+        # entry per application endpoint (or whole application) and
+        # environment. An entry: <tt>{"id", "api_package_id",
+        # "application_id", "endpoint_id", "all_endpoints", "endpoint",
+        # "environment_id", "inserted_at"}</tt>. @return [Page]
+        def list_endpoints(api_package_id, limit: nil, after: nil)
+          list_page(path("api_packages", api_package_id, "endpoints"), limit, after)
+        end
+
+        # Every entry of the package, across pages. @return [Enumerator, nil]
+        def each_endpoint(api_package_id, limit: nil, &block)
+          each_item(path("api_packages", api_package_id, "endpoints"), limit, &block)
+        end
+
+        # POST /api_packages/:id/endpoints. Leave +endpoint_id+ nil to publish
+        # every endpoint of the application.
+        #
+        # Answers the whole body, not only +data+: <tt>{"data" => entry,
+        # "warnings" => [...]}</tt>. Each warning (code
+        # +assignment_derives_nothing+) names a client assignment of the
+        # package that derives no grant.
+        #
+        # @return [Hash] <tt>{"data", "warnings"}</tt>
+        def add_endpoint(api_package_id, application_id:, environment_id:, endpoint_id: nil, idempotency_key: nil)
+          body = compact(application_id: application_id, endpoint_id: endpoint_id, environment_id: environment_id)
+          @transport.request("POST", path("api_packages", api_package_id, "endpoints"),
+                             body: body, idempotency_key: idempotency_key)
+        end
+
+        # DELETE /api_packages/:id/endpoints/:access_id. Answers the whole
+        # body, as {#add_endpoint} does.
+        #
+        # @return [Hash] <tt>{"data" => {"id", "deleted"}, "warnings" => [...]}</tt>
+        def remove_endpoint(api_package_id, access_id)
+          @transport.request("DELETE", path("api_packages", api_package_id, "endpoints", access_id))
+        end
+      end
+
+      # +GET /endpoints+: the endpoints of your organization's applications,
+      # to find the ids {ApiPackages#add_endpoint} takes.
+      #
+      # An endpoint: <tt>{"id", "application_id", "path", "action", "public",
+      # "inserted_at", "updated_at"}</tt>.
+      class Endpoints < Base
+        # @param application_id [String, nil] only this application's endpoints
+        # @param version [String, nil] only endpoints deployed in an
+        #   application version of this name
+        # @return [Page]
+        def list(application_id: nil, version: nil, limit: nil, after: nil)
+          list_page(path("endpoints"), limit, after, application_id: application_id, version: version)
+        end
+
+        # Every matching endpoint, across pages. @return [Enumerator, nil]
+        def each(application_id: nil, version: nil, limit: nil, &block)
+          each_item(path("endpoints"), limit, { application_id: application_id, version: version }, &block)
+        end
+      end
+    end
+  end
+end

data/lib/end_point_blank/management/resources/applications.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module EndPointBlank
+  module Management
+    module Resources
+      # +/applications+, and each application's environments
+      # (+/applications/:application_id/environments+, an "application
+      # environment": the application placed in an environment at a base URL).
+      #
+      # An application: <tt>{"id", "name", "public", "organization_group_id",
+      # "synced_at", "inserted_at", "updated_at"}</tt>. An application
+      # environment: <tt>{"id", "application_id", "environment_id",
+      # "base_url", ...}</tt>.
+      class Applications < Base
+        # @return [Page]
+        def list(limit: nil, after: nil)
+          list_page(path("applications"), limit, after)
+        end
+
+        # @return [Enumerator, nil]
+        def each(limit: nil, &block)
+          each_item(path("applications"), limit, &block)
+        end
+
+        # @return [Hash]
+        def get(id)
+          get_data(path("applications", id))
+        end
+
+        # POST /applications.
+        #
+        # @param environment_base_urls [Hash] environment id => base URL; at
+        #   least one is required
+        # @return [Hash] the new application
+        def create(name:, environment_base_urls:, public: nil, organization_group_id: nil, idempotency_key: nil)
+          body = compact(name: name, environment_base_urls: environment_base_urls, public: public,
+                         organization_group_id: organization_group_id)
+          post_data(path("applications"), body, idempotency_key)
+        end
+
+        # PATCH /applications/:id. Only the arguments given are sent.
+        # @return [Hash]
+        def update(id, name: nil, public: nil)
+          patch_data(path("applications", id), compact(name: name, public: public))
+        end
+
+        # DELETE /applications/:id. Refused with +has_dependents+ while grants
+        # or credentials depend on it. @return [Hash] <tt>{"id", "deleted"}</tt>
+        def delete(id)
+          delete_data(path("applications", id))
+        end
+
+        # GET /applications/:application_id/environments. @return [Page]
+        def list_environments(application_id, limit: nil, after: nil)
+          list_page(path("applications", application_id, "environments"), limit, after)
+        end
+
+        # @return [Enumerator, nil]
+        def each_environment(application_id, limit: nil, &block)
+          each_item(path("applications", application_id, "environments"), limit, &block)
+        end
+
+        # POST /applications/:application_id/environments: place the
+        # application in an environment at +base_url+.
+        # @return [Hash] the application environment
+        def add_environment(application_id, environment_id:, base_url:, idempotency_key: nil)
+          post_data(path("applications", application_id, "environments"),
+                    { environment_id: environment_id, base_url: base_url }, idempotency_key)
+        end
+
+        # DELETE /applications/:application_id/environments/:id, where +id+ is
+        # the application environment's id. @return [Hash] <tt>{"id", "deleted"}</tt>
+        def remove_environment(application_id, id)
+          delete_data(path("applications", application_id, "environments", id))
+        end
+      end
+
+      # +/environments+: deployment environments.
+      #
+      # An environment: <tt>{"id", "name", "domain", "is_default", ...}</tt>.
+      class Environments < Base
+        # @return [Page]
+        def list(limit: nil, after: nil)
+          list_page(path("environments"), limit, after)
+        end
+
+        # @return [Enumerator, nil]
+        def each(limit: nil, &block)
+          each_item(path("environments"), limit, &block)
+        end
+
+        # @return [Hash]
+        def get(id)
+          get_data(path("environments", id))
+        end
+
+        # POST /environments. @return [Hash] the new environment
+        def create(name:, domain:, is_default: nil, idempotency_key: nil)
+          post_data(path("environments"), compact(name: name, domain: domain, is_default: is_default),
+                    idempotency_key)
+        end
+
+        # PATCH /environments/:id. Only the arguments given are sent. The
+        # production environment answers +protected+. @return [Hash]
+        def update(id, name: nil, domain: nil, is_default: nil)
+          patch_data(path("environments", id), compact(name: name, domain: domain, is_default: is_default))
+        end
+
+        # DELETE /environments/:id. @return [Hash] <tt>{"id", "deleted"}</tt>
+        def delete(id)
+          delete_data(path("environments", id))
+        end
+      end
+
+      # +/credentials+: runtime client credentials (the client_id and
+      # client_secret an SDK authenticates with).
+      #
+      # A credential: <tt>{"id", "client_id", "secret_last_4",
+      # "application_environment_id", "application_id", "environment",
+      # "previous_secret", "expired_at", "created_at", "updated_at"}</tt>.
+      # {#create} and {#rotate} add +client_secret+, the only time the secret
+      # is ever returned: store it then. This SDK never logs it.
+      class Credentials < Base
+        # @param application_environment_id [String, nil] only this
+        #   application environment's credentials
+        # @return [Page] metadata only, no secrets
+        def list(application_environment_id: nil, limit: nil, after: nil)
+          list_page(path("credentials"), limit, after, application_environment_id: application_environment_id)
+        end
+
+        # @return [Enumerator, nil]
+        def each(application_environment_id: nil, limit: nil, &block)
+          each_item(path("credentials"), limit, { application_environment_id: application_environment_id }, &block)
+        end
+
+        # @return [Hash] metadata only, no secret
+        def get(id)
+          get_data(path("credentials", id))
+        end
+
+        # POST /credentials. A retry of a create that succeeded but whose
+        # answer was lost raises +idempotency_replay_unavailable+: list the
+        # application environment's credentials instead.
+        # @return [Hash] the credential, with its one-time +client_secret+
+        def create(application_environment_id:, idempotency_key: nil)
+          post_data(path("credentials"), { application_environment_id: application_environment_id }, idempotency_key)
+        end
+
+        # POST /credentials/:id/rotate: a new secret; the old one keeps
+        # working for the grace window (see +previous_secret+).
+        # @return [Hash] the credential, with its new one-time +client_secret+
+        def rotate(id, idempotency_key: nil)
+          post_data(path("credentials", id, "rotate"), nil, idempotency_key)
+        end
+
+        # DELETE /credentials/:id: revokes the credential on intake, then
+        # removes it. @return [Hash] <tt>{"id", "deleted"}</tt>
+        def delete(id)
+          delete_data(path("credentials", id))
+        end
+        alias revoke delete
+      end
+    end
+  end
+end