end_point_blank 0.12.0 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97bfbad03254a86968687a6f11f10c566b6357bf1294c82521fe8216261586eb
-  data.tar.gz: 28512438acaea4072288edd364cf246f307abf64cbb2e64eb6decd66f8295b0b
+  metadata.gz: 14c18a9f81130c9ec607b05a25aa5a4a67d9726c6692eb313a395734ce79bcf3
+  data.tar.gz: 4081ad91a0c10503521993a7d2d7887cd0810faab8b8f22229a57f9ed7685749
 SHA512:
-  metadata.gz: cdb4c6de628daa762e7c17925d96b51dd4cc26379531de385b61cfcb44fbf8c87c6a87f14b3c104fe4c1f5bd5ffdc953ee16f8ff36a61c0d4a90dfe9c2701ba7
-  data.tar.gz: 9fd76a38f763fd134758d9b4c89792bd983f707821008dfc9cf4f341fd8a35f53d9455c93c965d20a9649667b076f77f0359d52bc96425966cc4c4770708250d
+  metadata.gz: 181770dadb24b746868274196d0600ff58d92ad7e430f2165b8ff7f59e376a0790ed027b9a8fb000b607b20698190755f5de5525ca78d540c198addab72c5fdd
+  data.tar.gz: 88593bf5bb77615e05d9277de7a4b167d5885a155cb9b30cfac83dbe0335003e84801abe7b826fe55ab81793b8990e0d39578bb05b2033bef2512a4cc5c11d6f

data/CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## 0.13.1
+
+### Security
+
+- **Request and response records no longer carry credentials or cookies
+  (sc-1470).** Both records carried every `HTTP_*` header of the request (the
+  response record sends the request's headers, not the response's), so unless
+  you had written a masking rule for it, a caller's `Authorization` header
+  (Basic `client_id:secret` or a bearer token) landed in your request and
+  response logs in EndPointBlank. `RequestWriter` and `ResponseWriter` now
+  leave out `Authorization`, `Proxy-Authorization`, `Cookie` and `Set-Cookie`,
+  in any letter case, before masking runs, so they are not in the payload the
+  rules and hook receive, and they are not sent at all. The list is
+  `EndPointBlank::Rack::Headers::SENSITIVE_HEADERS`; the SDK's own reads of
+  the request (`Headers.extract`, used to find the endpoint version) are
+  unchanged. A masking rule that targeted one of these headers now has nothing
+  to match and can be removed. Records sent by earlier versions may hold these
+  values; rotate any client secret a caller sent while it was in use.
+
+### Upgrading
+
+- A `mask_hook` that reads `Authorization`, `Proxy-Authorization`, `Cookie` or
+  `Set-Cookie` from `headers` now finds it absent; guard the lookup.
+
+### Added
+
+- **`claim_invite` takes an optional `return_to` (sc-1515).**
+  `clients.claim_invite(client_id, email:, return_to:)` and a managed
+  client's `claim_invite(email:, return_to:)` send `return_to`, where
+  EndPointBlank sends the customer's browser once they have claimed the
+  managed client. It is sent only when given, and must equal, byte for byte,
+  a claim return URL your organization registered in EndPointBlank; anything
+  else is refused with `return_to_not_registered` (422), now in
+  `ErrorCodes` as `RETURN_TO_NOT_REGISTERED`.
+
+## 0.13.0
+
+### Added
+
+- **A client for the organization management API (sc-1505).**
+  `EndPointBlank::Management::Client` calls app_portal's `/api/v1` so a
+  provider can manage its EndPointBlank setup from code instead of
+  hand-rolling HTTP calls: the organization (`organization`), API packages
+  and what they publish (`api_packages`, `endpoints`), clients and their
+  invites (`clients`, including `invite` with pre-assigned `packages` and
+  `grants`, and `create_managed`), package assignments
+  (`package_assignments`), direct grants (`grants`), `applications` and their
+  environments, `environments`, and runtime `credentials` (create and
+  `rotate` return the one-time `client_secret`). `for_managed_client(id)`
+  gives the same applications, environments and credentials calls for a
+  managed client, under `/clients/:client_id/`, plus `claim_invite`.
+
+  It is plain Ruby (no Rails needed) and separate from the runtime
+  configuration: it authenticates only with a management API key, sent as
+  `Authorization: Bearer epb_mk_...`, refuses at construction a key without
+  that prefix, never sends the runtime `client_id`/`client_secret`, never
+  calls intake, and never shows the key in `inspect`, `to_s` or an error
+  message. Defaults come from `EndPointBlank::Management.configure` (e.g. a
+  Rails initializer) or `ENDPOINTBLANK_MANAGEMENT_KEY` /
+  `ENDPOINTBLANK_MANAGEMENT_BASE_URL`, and the base URL defaults to
+  `https://app.endpointblank.com`.
+
+  - Lists answer an `EndPointBlank::Management::Page` (`data`,
+    `next_cursor`); each list's `each` walks every page lazily, as an
+    `Enumerator` without a block.
+  - Every POST sends an `Idempotency-Key` (a random UUID v4 unless you pass
+    `idempotency_key:`), and a retry sends the same one.
+  - A 429 is retried after its `Retry-After` seconds (1 second without
+    one); a 5xx or a request that got no answer is retried with backoff for
+    GET, DELETE and POST, never for PATCH; `idempotency_request_in_progress` is retried with the
+    same key. At most 2 retries by default (`max_retries:`, `0` turns them
+    off), and no single wait longer than `max_retry_wait:` (60 seconds).
+  - Every refusal raises `EndPointBlank::Management::Error` (a subclass of
+    `EndPointBlank::Error`) with `code`, `message`, `details`, `status`,
+    `retry_after`, `location` and `request_id`. `ErrorCodes` lists every
+    code the API documents; a code it does not know still raises with that
+    code. `idempotency_replay_unavailable` is never retried, and its message
+    says to read or list the resource instead.
+  - Uses Excon, already a dependency; no new runtime dependency.
+
 ## 0.12.0
 
 ### Breaking changes

data/README.md

@@ -16,6 +16,9 @@ auto-loads (railtie + middleware) when Rails is present.
 - **Client-side data masking** (`EndPointBlank::Masking` / `masking_rules`) — strip or redact
   sensitive fields from payloads *before* they leave your process, as defense in depth on top of
   server-side masking.
+- **Management API client** (`EndPointBlank::Management::Client`) — manage API packages, clients,
+  grants, applications, environments, credentials and managed clients from code. See
+  [Management API](#management-api).
 - **Framework-agnostic core** — `EndPointBlank::Middleware::Rack::ReportInteraction` and the
   writers work directly against Rack env/`::Rack::Request`, so the gem behaves correctly under
   plain Ruby, Sinatra, or any Rack app. When `::Rails` is defined, a `Railtie` auto-inserts the
@@ -482,6 +485,11 @@ regex is applied only within the path-selected node(s). When a `regex` is presen
 match; `$$` for a literal `$`). Stacktraces and log messages/data are never masked (there is no
 `log` entry in the masking field map).
 
+**Credential and cookie headers are never sent.** Before any rule runs, the request and response
+records leave out `Authorization`, `Proxy-Authorization`, `Cookie` and `Set-Cookie`, whatever
+their letter case. They are left out of the record, not masked: they are not in the payload the
+rules and hook receive. The list is `EndPointBlank::Rack::Headers::SENSITIVE_HEADERS`.
+
 ## Framework integration
 
 ### Rails
@@ -548,6 +556,196 @@ and clears the env store, reporting any raised exception via `ExceptionWriter` a
 reads/writes plain Rack request objects (`::Rack::Request`), so it works identically under any
 Rack-compatible server or framework, not only Sinatra.
 
+## Management API
+
+`EndPointBlank::Management::Client` manages your organization's EndPointBlank setup from code:
+API packages, clients and their invites, package assignments, direct grants, applications,
+environments, runtime credentials, and the managed clients you run for your customers. It calls
+app_portal's management API (`https://app.endpointblank.com/api/v1`). See the
+[guide](https://app.endpointblank.com/docs/management-api) and the
+[reference](https://app.endpointblank.com/docs/management-api-reference).
+
+It is plain Ruby, usable from a script, a job or a console as well as a Rails app, and it is
+**separate from the runtime configuration above**. It authenticates only with a management API
+key (create one in the portal under Settings > API Keys), sent as
+`Authorization: Bearer epb_mk_...`. It never sends your runtime `client_id`/`client_secret`, never
+calls intake, and never shows the key in `inspect`, `to_s` or an error message. A key without the
+`epb_mk_` prefix is refused when the client is built, with `EndPointBlank::ConfigurationError`.
+
+### Quick start
+
+```ruby
+require "end_point_blank"
+
+mgmt = EndPointBlank::Management::Client.new(api_key: ENV.fetch("EPB_MGMT_KEY"))
+
+mgmt.organization  # => {"id" => "...", "name" => "Acme", "slug" => "acme", "key" => {"name" => "ci", "scope" => "write"}, ...}
+
+# One page at a time (limit 1..100, default 50) ...
+page = mgmt.applications.list(limit: 20)
+page.data         # => [{"id" => "...", "name" => "Orders", ...}, ...]
+page.next_cursor  # => pass as `after:` for the next page; nil on the last one
+
+# ... or every item, fetching pages as it goes (an Enumerator without a block).
+mgmt.applications.each { |application| puts application["name"] }
+names = mgmt.api_packages.each(limit: 100).map { |package| package["name"] }
+```
+
+Every call answers what the API sent, decoded from JSON into Hashes with String keys: the
+resource itself (the response's `data`), a `Page` for a list, and `{"id" => ..., "deleted" => true}`
+for a delete. `api_packages.add_endpoint` and `remove_endpoint` answer the whole body,
+`{"data" => ..., "warnings" => [...]}`, so the `assignment_derives_nothing` warnings are not lost.
+Optional keyword arguments left `nil` are not sent.
+
+### Invite a client and assign an API package
+
+```ruby
+# Environment names are unique per organization, and "production" is reserved for the one every
+# organization already has; look an existing one up with mgmt.environments.each instead.
+staging = mgmt.environments.create(name: "staging", domain: "staging.example.com")
+orders  = mgmt.applications.create(name: "Orders",
+                                   environment_base_urls: { staging["id"] => "https://orders.staging.example.com" })
+
+package = mgmt.api_packages.create(name: "Orders read")
+
+# An application's endpoints are listed once its runtime SDK has reported them, so a just-created
+# application has none yet. Publish one endpoint when it is there, else the whole application
+# (endpoint_id nil covers every endpoint, including ones reported later).
+endpoint = mgmt.endpoints.each(application_id: orders["id"]).find { |e| e["path"] == "/orders" && e["action"] == "GET" }
+mgmt.api_packages.add_endpoint(package["id"], application_id: orders["id"], endpoint_id: endpoint&.fetch("id"),
+                                              environment_id: staging["id"])
+```
+
+Then give a client the package in one of two ways; doing both for the same package and environment
+is refused with `already_assigned`.
+
+```ruby
+# Either: set it up on the invite, and it is assigned the moment the client accepts.
+globex = mgmt.clients.invite(
+  name: "Globex",
+  contacts: [{ email: "dev@globex.example", first_name: "Hank", last_name: "Scorpio" }],
+  packages: [{ api_package_id: package["id"], environment_id: staging["id"] }]
+)
+globex["invite_code"]  # send this to the client; it accepts from its own EndPointBlank organization
+
+# Or: invite first, then assign (pending until the client accepts, active after) and grant directly.
+initrode = mgmt.clients.invite(name: "Initrode")
+mgmt.package_assignments.assign(initrode["id"], api_package_id: package["id"], environment_id: staging["id"])
+mgmt.grants.create(initrode["id"], target_application_id: orders["id"], environment_id: staging["id"])
+```
+
+### Runtime credentials
+
+```ruby
+app_env = mgmt.applications.list_environments(orders["id"]).first
+credential = mgmt.credentials.create(application_environment_id: app_env["id"])
+credential["client_id"]
+credential["client_secret"]  # shown once, here and nowhere else: store it now
+
+rotated = mgmt.credentials.rotate(credential["id"])
+rotated["client_secret"]     # the new secret; the old one keeps working for the grace window
+
+mgmt.credentials.revoke(credential["id"])
+```
+
+`list` and `get` answer metadata only (`secret_last_4`, never the secret). This SDK never logs a
+secret, the key, or any request or response body.
+
+### Managed clients
+
+A managed client is an organization you create and run for a customer until they claim it.
+`for_managed_client(id)` gives the same applications, environments and credentials calls, sent
+under `/api/v1/clients/:client_id/`:
+
+```ruby
+customer = mgmt.clients.create_managed(name: "Initech")
+initech  = mgmt.for_managed_client(customer["id"])
+
+# The managed client's organization already has a "production" environment (the name is
+# reserved); create others alongside it.
+initech_staging = initech.environments.create(name: "staging", domain: "staging.initech.example")
+billing_url = "https://billing.staging.initech.example"
+app = initech.applications.create(name: "Initech billing",
+                                  environment_base_urls: { initech_staging["id"] => billing_url })
+app_env = initech.applications.list_environments(app["id"]).first
+secret = initech.credentials.create(application_environment_id: app_env["id"])["client_secret"]
+
+# Grant it your APIs like any accepted client (package and staging from the example above) ...
+mgmt.package_assignments.assign(customer["id"], api_package_id: package["id"], environment_id: staging["id"])
+
+# ... and hand it over: the customer gets an email, and claiming rotates every credential you issued.
+initech.claim_invite(email: "it@initech.example")
+
+# Optionally send the customer's browser somewhere once they have claimed it. `return_to` must
+# equal, byte for byte, a claim return URL your organization registered in EndPointBlank;
+# anything else is refused with `return_to_not_registered` (422).
+initech.claim_invite(email: "it@initech.example", return_to: "https://app.example/welcome")
+```
+
+Once claimed, the managed client's calls answer `not_found`. Remove an unclaimed one with
+`mgmt.clients.delete(customer["id"])` after revoking its credentials.
+
+### Errors, retries and idempotency
+
+Every refusal raises `EndPointBlank::Management::Error` (a subclass of `EndPointBlank::Error`)
+with `code`, `message`, `details`, `status`, `retry_after`, `location` and `request_id`. Match on
+`code`, which is stable; `message` is for people. `EndPointBlank::Management::ErrorCodes` has a
+constant for every code the API documents, and an unknown code still raises with that code.
+
+```ruby
+codes = EndPointBlank::Management::ErrorCodes
+
+begin
+  mgmt.clients.invite(name: "Umbrella")
+rescue EndPointBlank::Management::Error => e
+  case e.code
+  when codes::PLAN_LIMIT        then warn "upgrade your plan to add clients"            # 402
+  when codes::VALIDATION_FAILED then warn "invalid fields: #{e.details.inspect}"        # 422
+  when codes::NOT_FOUND         then warn "no such resource"                            # 404
+  when codes::INSUFFICIENT_SCOPE then warn "this is a read-only key"                    # 403
+  else raise
+  end
+end
+```
+
+The SDK raises three codes of its own: `connection_error` (no answer at all; `status` is nil),
+`http_error` (an error answer that is not the API's JSON, e.g. from a proxy) and
+`invalid_response` (a success answer that is not JSON).
+
+- **Idempotency.** Every POST sends an `Idempotency-Key`: a random UUID unless you pass
+  `idempotency_key:` (1 to 255 characters), and a retry sends the same key, so a POST is never run
+  twice. A credential `create` or `rotate` retried after the first one succeeded raises
+  `idempotency_replay_unavailable` instead of replaying the secret: read or list the credential
+  (rotate it if you never got the secret).
+- **Retries.** A 429 `rate_limited` is retried after its `Retry-After` seconds (1 second
+  when it has none). A 5xx
+  (`internal_server_error`, `audit_unavailable`, `intake_unavailable`) or a request that got no
+  answer is retried with backoff for GET, DELETE and POST, never for PATCH.
+  `idempotency_request_in_progress` is retried shortly with the same key. 4xx refusals are never
+  retried.
+
+| `Client.new` option | Env var fallback | Default | Notes |
+|---|---|---|---|
+| `api_key` | `ENDPOINTBLANK_MANAGEMENT_KEY` | none (required) | A management API key, `epb_mk_...`. |
+| `base_url` | `ENDPOINTBLANK_MANAGEMENT_BASE_URL` | `https://app.endpointblank.com` | app_portal, not intake. |
+| `max_retries` | — | `2` | Retries after the first attempt; `0` turns them off. |
+| `max_retry_wait` | — | `60` | The longest single wait, in seconds; a longer `Retry-After` raises instead. |
+| `connect_timeout` / `read_timeout` | — | `5` / `30` | Seconds. |
+| `sleeper` | — | `Kernel#sleep` | Called with the seconds before each retry (replace it in tests). |
+| `excon_options` | — | `{}` | Extra `Excon.new` options, e.g. a proxy. |
+
+In a Rails app, set the defaults once in an initializer, apart from `EndPointBlank.configure`:
+
+```ruby
+# config/initializers/end_point_blank_management.rb
+EndPointBlank::Management.configure do |m|
+  m.api_key = Rails.application.credentials.dig(:end_point_blank, :management_key)
+  m.max_retries = 3
+end
+
+EndPointBlank::Management.client.organization  # a Client built from that configuration
+```
+
 ## Development
 
 ```sh

data/lib/end_point_blank/management/client.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "configuration"
+require_relative "error"
+require_relative "transport"
+require_relative "resources/base"
+require_relative "resources/api_packages"
+require_relative "resources/clients"
+require_relative "resources/applications"
+
+module EndPointBlank
+  module Management
+    # A client for the EndPointBlank organization management API (app_portal's
+    # +/api/v1+): your organization's API packages, clients, package
+    # assignments, grants, applications, environments and runtime credentials,
+    # and the managed clients you run for your customers.
+    #
+    # Plain Ruby: usable from a script, a job or a console as well as a Rails
+    # app. It authenticates only with a management API key
+    # (<tt>Authorization: Bearer epb_mk_...</tt>, created in the portal under
+    # Settings > API Keys) and shares nothing with the runtime configuration:
+    # it never sends a runtime client_id/client_secret and never calls intake.
+    #
+    #   mgmt = EndPointBlank::Management::Client.new(api_key: ENV.fetch("EPB_MGMT_KEY"))
+    #   mgmt.organization                  # => {"id" => ..., "name" => ..., ...}
+    #   mgmt.api_packages.each { |package| puts package["name"] }
+    #
+    # Arguments left nil fall back to {Management.configure} (and its
+    # ENDPOINTBLANK_MANAGEMENT_* environment variables), then the defaults.
+    #
+    # Thread-safe: each request opens its own connection.
+    class Client
+      KEY_PREFIX = "epb_mk_"
+      # The prefix and the rest of the key in the alphabet app_portal mints it
+      # in (URL-safe base64): nothing else can be a valid key, so nothing else
+      # is ever put in a header.
+      KEY_FORMAT = /\Aepb_mk_[A-Za-z0-9_-]+\z/.freeze
+
+      # The options {#initialize} takes besides api_key and base_url.
+      OPTIONS = %i[max_retries max_retry_wait connect_timeout read_timeout sleeper excon_options].freeze
+
+      DEFAULT_SLEEPER = ->(seconds) { Kernel.sleep(seconds) }
+
+      # @return [Resources::ApiPackages]
+      attr_reader :api_packages
+      # @return [Resources::Endpoints]
+      attr_reader :endpoints
+      # @return [Resources::Clients]
+      attr_reader :clients
+      # @return [Resources::PackageAssignments]
+      attr_reader :package_assignments
+      # @return [Resources::Grants]
+      attr_reader :grants
+      # @return [Resources::Applications]
+      attr_reader :applications
+      # @return [Resources::Environments]
+      attr_reader :environments
+      # @return [Resources::Credentials]
+      attr_reader :credentials
+
+      # @param api_key [String] a management API key, epb_mk_...
+      # @param base_url [String] app_portal's URL (default https://app.endpointblank.com)
+      # @param max_retries [Integer] retries after the first attempt; 0 turns them off
+      # @param max_retry_wait [Numeric] the longest single wait, in seconds
+      # @param connect_timeout [Numeric] seconds
+      # @param read_timeout [Numeric] seconds
+      # @param sleeper [#call] called with the seconds to wait before a retry
+      #   (default Kernel#sleep); replace it in tests
+      # @param excon_options [Hash] extra options for Excon.new (e.g. a proxy,
+      #   or <tt>mock: true</tt> with Excon.stub in tests)
+      # @raise [EndPointBlank::ConfigurationError] for a missing or malformed key or base URL
+      def initialize(api_key: nil, base_url: nil, **options)
+        unknown = options.keys - OPTIONS
+        raise ArgumentError, "unknown option(s): #{unknown.join(", ")}" unless unknown.empty?
+
+        config = Management.configuration
+        @transport = Transport.new(
+          api_key: self.class.validate_key(api_key || config.api_key),
+          base_url: self.class.validate_base_url(base_url || config.base_url),
+          **transport_options(config, options)
+        )
+        build_resources
+      end
+
+      # app_portal's URL this client calls.
+      def base_url
+        @transport.base_url
+      end
+
+      # GET /organization: the organization the key belongs to, and the key's
+      # name and scope.
+      # @return [Hash] <tt>{"id", "name", "domain", "slug", "key" => {"name", "scope"}}</tt>
+      def organization
+        body = @transport.request("GET", "/organization")
+        body.is_a?(Hash) ? body["data"] : body
+      end
+
+      # A view of the API as your managed client +client_id+ (a client
+      # created with <tt>clients.create_managed</tt>): its applications,
+      # environments and credentials, under /clients/:client_id/. Works only
+      # while the client is unclaimed; afterwards every call answers 404.
+      #
+      # @return [ManagedClient]
+      def for_managed_client(client_id)
+        ManagedClient.new(@transport, client_id, @clients)
+      end
+
+      # Never shows the key.
+      def inspect
+        "#<#{self.class.name} base_url=#{base_url.inspect} api_key=[REDACTED]>"
+      end
+      alias to_s inspect
+
+      # The key, if it is a management API key. The error never repeats it.
+      # @api private
+      def self.validate_key(api_key)
+        key = normalized_key(api_key)
+        return key if key&.match?(KEY_FORMAT)
+
+        given = key.nil? || key.empty? ? "No key was given" : "The key given does not have that form"
+        raise EndPointBlank::ConfigurationError,
+              "EndPointBlank::Management::Client needs a management API key: #{KEY_PREFIX} followed by " \
+              "the rest of the key, as the portal shows it under Settings > API Keys. #{given}. " \
+              "Runtime client credentials are not accepted by the management API."
+      end
+
+      # +api_key+ without surrounding whitespace (a key read from a file or an
+      # env var often ends in a newline), or nil when it is not a readable
+      # String at all.
+      def self.normalized_key(api_key)
+        return nil unless api_key.is_a?(String) && api_key.valid_encoding? && api_key.encoding.ascii_compatible?
+
+        api_key.strip
+      end
+      private_class_method :normalized_key
+
+      # +base_url+ without a trailing slash, if it is an http(s) URL with a
+      # host and no userinfo, query or fragment. The error never repeats it,
+      # since a URL can carry credentials.
+      # @api private
+      def self.validate_base_url(base_url)
+        return UrlPath.strip_trailing_slashes(base_url.to_s) if plain_http_url?(base_url)
+
+        raise EndPointBlank::ConfigurationError,
+              "The management API base_url must be an http(s) URL with a host and no userinfo, " \
+              "query or fragment, such as #{Configuration::DEFAULT_BASE_URL}."
+      end
+
+      def self.plain_http_url?(base_url)
+        uri = URI.parse(base_url.to_s)
+        %w[http https].include?(uri.scheme) && !uri.host.to_s.empty? &&
+          [uri.userinfo, uri.query, uri.fragment].all?(&:nil?)
+      rescue URI::InvalidURIError
+        false
+      end
+      private_class_method :plain_http_url?
+
+      private
+
+      def transport_options(config, options)
+        {
+          max_retries: non_negative(:max_retries, options.fetch(:max_retries, config.max_retries)),
+          max_retry_wait: non_negative(:max_retry_wait, options.fetch(:max_retry_wait, config.max_retry_wait)),
+          connect_timeout: options.fetch(:connect_timeout, config.connect_timeout),
+          read_timeout: options.fetch(:read_timeout, config.read_timeout),
+          sleeper: options.fetch(:sleeper, DEFAULT_SLEEPER),
+          excon_options: options.fetch(:excon_options, {})
+        }
+      end
+
+      def non_negative(name, value)
+        return value if value.is_a?(Numeric) && !value.negative?
+
+        raise ArgumentError, "#{name} must be a non-negative number, got #{value.inspect}"
+      end
+
+      def build_resources
+        @api_packages = Resources::ApiPackages.new(@transport)
+        @endpoints = Resources::Endpoints.new(@transport)
+        @clients = Resources::Clients.new(@transport)
+        @package_assignments = Resources::PackageAssignments.new(@transport)
+        @grants = Resources::Grants.new(@transport)
+        @applications = Resources::Applications.new(@transport)
+        @environments = Resources::Environments.new(@transport)
+        @credentials = Resources::Credentials.new(@transport)
+      end
+    end
+
+    # Your managed client's applications, environments and credentials, from
+    # {Client#for_managed_client}. The same calls as the {Client}'s own,
+    # sent under /api/v1/clients/:client_id/.
+    class ManagedClient
+      # @return [String] the client's id (as in /clients/:client_id)
+      attr_reader :client_id
+      # @return [Resources::Applications]
+      attr_reader :applications
+      # @return [Resources::Environments]
+      attr_reader :environments
+      # @return [Resources::Credentials]
+      attr_reader :credentials
+
+      def initialize(transport, client_id, clients)
+        prefix = "/clients/#{Resources::Base.escape(client_id)}"
+        @client_id = client_id
+        @clients = clients
+        @applications = Resources::Applications.new(transport, prefix)
+        @environments = Resources::Environments.new(transport, prefix)
+        @credentials = Resources::Credentials.new(transport, prefix)
+      end
+
+      # The client itself (GET /clients/:client_id). @return [Hash]
+      def get
+        @clients.get(client_id)
+      end
+
+      # POST /clients/:client_id/claim_invites: emails your customer an
+      # invite to claim the client, and with +return_to+ (a claim return URL
+      # your organization registered) where to send them once claimed; see
+      # {Resources::Clients#claim_invite}. @return [Hash]
+      def claim_invite(email:, return_to: nil, idempotency_key: nil)
+        @clients.claim_invite(client_id, email: email, return_to: return_to, idempotency_key: idempotency_key)
+      end
+
+      def inspect
+        "#<#{self.class.name} client_id=#{client_id.inspect}>"
+      end
+    end
+  end
+end

data/lib/end_point_blank/management/configuration.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module EndPointBlank
+  module Management
+    # Defaults for {Client.new}, set with {Management.configure}, e.g. in a
+    # Rails initializer.
+    #
+    # Separate from {EndPointBlank::Configuration} on purpose: the runtime
+    # client_id/client_secret are never sent to the management API, and the
+    # management key is never sent to intake. Nothing here reads the runtime
+    # configuration, and nothing in the runtime configuration reads this.
+    class Configuration
+      DEFAULT_BASE_URL = "https://app.endpointblank.com"
+      DEFAULT_MAX_RETRIES = 2
+      DEFAULT_MAX_RETRY_WAIT = 60
+      DEFAULT_CONNECT_TIMEOUT = 5
+      DEFAULT_READ_TIMEOUT = 30
+
+      attr_writer :api_key, :base_url
+
+      # Retries after the first attempt (see {Transport}). 0 turns them off.
+      attr_accessor :max_retries
+      # The longest wait, in seconds, a retry will sleep (a longer
+      # Retry-After raises the error instead).
+      attr_accessor :max_retry_wait
+      attr_accessor :connect_timeout, :read_timeout
+
+      def initialize
+        @max_retries = DEFAULT_MAX_RETRIES
+        @max_retry_wait = DEFAULT_MAX_RETRY_WAIT
+        @connect_timeout = DEFAULT_CONNECT_TIMEOUT
+        @read_timeout = DEFAULT_READ_TIMEOUT
+      end
+
+      # The management API key (epb_mk_...), falling back to the
+      # ENDPOINTBLANK_MANAGEMENT_KEY environment variable.
+      def api_key
+        @api_key || ENV.fetch("ENDPOINTBLANK_MANAGEMENT_KEY", nil)
+      end
+
+      # app_portal's URL, falling back to the
+      # ENDPOINTBLANK_MANAGEMENT_BASE_URL environment variable, then
+      # {DEFAULT_BASE_URL}. Not the runtime's intake base_url.
+      def base_url
+        @base_url || ENV.fetch("ENDPOINTBLANK_MANAGEMENT_BASE_URL", nil) || DEFAULT_BASE_URL
+      end
+
+      # Never shows the key.
+      def inspect
+        "#<#{self.class.name} base_url=#{base_url.inspect} api_key=#{api_key ? "[REDACTED]" : "nil"} " \
+          "max_retries=#{max_retries.inspect}>"
+      end
+      alias to_s inspect
+    end
+  end
+end