open_blog 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efdb8a5a4e6810822b5821360a7dafa544d704135f98ef877c226d7ae7888117
-  data.tar.gz: e15a793d38b597451baf0accb892cc5cb73ab4e86fa82fc90a04e6ea45807d9c
+  metadata.gz: 73849fe8c16692737f1e4ef73f9c2081832b804c1f07f5263c04d17fecc8340e
+  data.tar.gz: 55ae82fb654aedab55a31ce1f9eaa19283483cb79dbb0bc82bf32b280e98bf8f
 SHA512:
-  metadata.gz: a6554c741ba91b63ef85d001ea36f25b62aad3b351407a6e46fff323e79204a52aa7fbedd3837c114fb96548fc3b312236e8562fbb613d03c4ac0ec504ec6a12
-  data.tar.gz: 6cb4979aab3f7ea903759ff765c3a9843a7d917a9a1965241fcf2f9326c6dc7b338fe88e597e69248233e77d194254e7c0c2aeb71c325adeaa7840069cea55b5
+  metadata.gz: f58ba9004bcc2d78f56d44792203a4c94626fb9b74dbcd16936428920b67811b0f6b3667a72aa9578045e591d12f1bc0565ac8fe3e29c0ab39a0a1b58781a5ed
+  data.tar.gz: 0d2909e6256bc77b2c46a0c81aa3a13536b096dfbcb46f6a3c638c675e2fbd8513f16e19d55931e7da284bfec15a1acd802092cf2a1876b7a7732603fb331610

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-29
+
+### Added
+
+- AdminSuite pages to issue, list, revoke, and rotate API tokens, with per-identity grants, expiry and grace policy, one-time secret reveal, and an audit trail. `open_blog:admin_suite` now writes `config/initializers/open_blog_api_tokens.rb` and `config/open_blog.yml`, and doctor reports whether token management is wired.
+- Add the `AddOpenBlogApiTokenManagement` migration. It adds the token owner and successor columns and the `open_blog_api_token_events` table.
+
+### Changed
+
+- A token issued in AdminSuite records its owner. The API actor for such a token is `"<name> (<identity>)"`, for example `"Deploy (admin:42)"`, so revision `actor`, publication `released_by`, approval and connection `recorded_by`, and image `uploaded_by` show that name. Tokens without an owner, such as ones from `open_blog:token`, keep the plain name.
+- `ApiToken` refuses an empty or repeated scope list. `SCOPES= bin/rails open_blog:token` now fails instead of issuing a token with no scopes, and `update!` on an existing token with no scopes fails until you give it a scope.
+- A token with audit events cannot be destroyed. Revoke it instead.
+- Doctor's **API token management** check runs when Open Blog's AdminSuite adapter is installed and names each missing piece: no identity hook, no grant policy, no grants in `config/open_blog.yml`, or tokens inactive because `config.authenticate` is set.
+
+### Upgrade notes
+
+- Run `bin/rails railties:install:migrations FROM=open_blog` and `bin/rails db:migrate`. Existing tokens and `open_blog:token` keep working before the migration runs; the AdminSuite token pages need it.
+- To revoke a token that has no scopes, use the AdminSuite page or `OpenBlog::ApiToken.find(id).update_column(:revoked_at, Time.current)`, because `update!` now fails validation for that token.
+
 ## [0.4.0] - 2026-10-28
 
 ### Changed

data/app/models/open_blog/api_token.rb

@@ -3,23 +3,44 @@ require "active_support/core_ext/securerandom"
 
 module OpenBlog
   class ApiToken < ApplicationRecord
-    SCOPES = %w[read write publish].freeze
+    SCOPES = ApiTokens::SCOPES
     scope :active, -> { where(revoked_at: nil).where("expires_at IS NULL OR expires_at > ?", Time.current) }
 
+    self.filter_attributes += %w[token_digest]
+
+    belongs_to :successor, class_name: "OpenBlog::ApiToken", optional: true
+    has_one :predecessor, class_name: "OpenBlog::ApiToken", foreign_key: :successor_id, inverse_of: :successor
+    has_many :events, class_name: "OpenBlog::ApiTokenEvent", dependent: :restrict_with_exception
+
     validates :name, presence: true
     validates :token_digest, presence: true, uniqueness: true, format: { with: /\A[0-9a-f]{64}\z/ }
     validates :token_prefix, length: { is: 8 }
     validate do
-      errors.add(:scopes, "must contain only read, write or publish") unless scopes.is_a?(Array) && (scopes - SCOPES).empty?
+      if !scopes.is_a?(Array) || (scopes - SCOPES).any?
+        errors.add(:scopes, "must contain only read, write or publish")
+      elsif scopes.empty?
+        errors.add(:scopes, "must not be empty")
+      elsif scopes.uniq.size != scopes.size
+        errors.add(:scopes, "must not repeat a scope")
+      end
     end
 
-    def self.generate(name:, scopes: SCOPES, expires_at: nil)
+    def self.generate(name:, scopes: SCOPES, expires_at: nil, creator_identity: nil)
       secret = "ob_#{SecureRandom.base58(40)}"
-      record = create!(name: name, scopes: scopes, expires_at: expires_at,
-        token_digest: Digest::SHA256.hexdigest(secret), token_prefix: secret[0, 8])
+      attributes = { name: name, scopes: scopes, expires_at: expires_at,
+        token_digest: Digest::SHA256.hexdigest(secret), token_prefix: secret[0, 8] }
+      attributes[:creator_identity] = creator_identity if creator_identity
+      record = create!(attributes)
       [ record, secret ]
     end
 
+    def status
+      if revoked_at then :revoked
+      elsif expires_at && expires_at <= Time.current then :expired
+      else :active
+      end
+    end
+
     def self.authenticate(secret)
       return unless secret.is_a?(String) && secret.match?(/\Aob_[1-9A-HJ-NP-Za-km-z]{40}\z/)
       digest = Digest::SHA256.hexdigest(secret)

data/app/models/open_blog/api_token_event.rb

@@ -0,0 +1,9 @@
+module OpenBlog
+  class ApiTokenEvent < ApplicationRecord
+    ACTIONS = %w[issued rotated revoked].freeze
+
+    belongs_to :api_token
+    validates :action, inclusion: { in: ACTIONS }
+    validates :actor_identity, presence: true
+  end
+end

data/app/views/open_blog/admin_suite/api_tokens/_banner.html.erb

@@ -0,0 +1,5 @@
+<% if tokens_inactive? %>
+  <div class="mb-6 rounded-lg border border-amber-300 bg-amber-50 p-4 text-sm text-amber-900" role="status">
+    This host uses its own API authentication hook. Tokens issued here would not work.
+  </div>
+<% end %>

data/app/views/open_blog/admin_suite/api_tokens/_error.html.erb

@@ -0,0 +1,3 @@
+<% if @error %>
+  <div class="mb-6 rounded-lg border border-red-300 bg-red-50 p-4 text-sm text-red-900" role="alert"><%= @error %></div>
+<% end %>

data/app/views/open_blog/admin_suite/api_tokens/error.html.erb

@@ -0,0 +1,6 @@
+<% content_for :title, "API tokens - Admin Suite" %>
+
+<div class="px-4 sm:px-6 lg:px-8 max-w-3xl mx-auto">
+  <h1 class="text-2xl font-bold text-slate-900 mb-4">API tokens</h1>
+  <p class="text-slate-700"><%= @message %></p>
+</div>

data/app/views/open_blog/admin_suite/api_tokens/index.html.erb

@@ -0,0 +1,47 @@
+<% content_for :title, "API tokens - Admin Suite" %>
+
+<div class="px-4 sm:px-6 lg:px-8">
+  <div class="mb-6 flex items-center justify-between">
+    <h1 class="text-2xl font-bold text-slate-900">API tokens</h1>
+    <% if grant.manage_own && !tokens_inactive? %>
+      <%= link_to "New token", new_open_blog_api_token_path, class: "px-4 py-2 rounded-lg bg-slate-900 text-white text-sm font-medium" %>
+    <% end %>
+  </div>
+
+  <%= render "banner" %>
+
+  <% if @tokens.empty? %>
+    <p class="text-slate-600">No API tokens yet.</p>
+  <% else %>
+    <div class="bg-white rounded-xl border border-slate-200 overflow-x-auto">
+      <table class="min-w-full text-sm">
+        <thead class="bg-slate-50 text-left text-slate-600">
+          <tr>
+            <th class="px-4 py-3">Name</th>
+            <th class="px-4 py-3">Prefix</th>
+            <th class="px-4 py-3">Scopes</th>
+            <th class="px-4 py-3">Owner</th>
+            <th class="px-4 py-3">Status</th>
+            <th class="px-4 py-3">Created</th>
+            <th class="px-4 py-3">Last used</th>
+            <th class="px-4 py-3">Expires</th>
+          </tr>
+        </thead>
+        <tbody class="divide-y divide-slate-100">
+          <% @tokens.each do |token| %>
+            <tr>
+              <td class="px-4 py-3"><%= link_to token.name, open_blog_api_token_path(token) %></td>
+              <td class="px-4 py-3 font-mono"><%= token.token_prefix %></td>
+              <td class="px-4 py-3"><%= token.scopes.join(", ") %></td>
+              <td class="px-4 py-3"><%= token.creator_identity || "No owner" %></td>
+              <td class="px-4 py-3"><%= token.status.to_s.humanize %></td>
+              <td class="px-4 py-3"><%= token_time(token.created_at) %></td>
+              <td class="px-4 py-3"><%= token.last_used_at ? token_time(token.last_used_at) : "Never" %></td>
+              <td class="px-4 py-3"><%= token.expires_at ? token_time(token.expires_at) : "Never" %></td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+  <% end %>
+</div>

data/app/views/open_blog/admin_suite/api_tokens/new.html.erb

@@ -0,0 +1,44 @@
+<% content_for :title, "New API token - Admin Suite" %>
+<% content_for :head do %>
+  <%= tag.style(<<~CSS.html_safe, nonce: content_security_policy_nonce) %>
+    form:has(input[name="scopes[]"][value="read"]:checked) .open-blog-read-warning { display: none; }
+  CSS
+<% end %>
+
+<div class="px-4 sm:px-6 lg:px-8 max-w-3xl mx-auto">
+  <nav class="mb-2 text-sm text-slate-500"><%= link_to "API tokens", open_blog_api_tokens_path %></nav>
+  <h1 class="text-2xl font-bold text-slate-900 mb-6">New API token</h1>
+
+  <%= render "banner" %>
+  <%= render "error" %>
+
+  <div class="bg-white rounded-xl border border-slate-200 p-6">
+    <%= form_with url: open_blog_api_tokens_path, method: :post, data: { turbo: false }, class: "space-y-6" do |form| %>
+      <div>
+        <%= form.label :name, "Name", class: "block text-sm font-medium text-slate-700" %>
+        <%= form.text_field :name, value: params[:name], required: true, maxlength: OpenBlog::ApiTokens::NAME_LENGTH.max, class: "form-input mt-1 w-full" %>
+      </div>
+
+      <fieldset>
+        <legend class="text-sm font-medium text-slate-700">Scopes</legend>
+        <% grant.scopes.each do |scope| %>
+          <label class="mt-2 flex items-center gap-2 text-sm">
+            <%= check_box_tag "scopes[]", scope, @scopes.include?(scope), id: "scope_#{scope}" %>
+            <%= scope %>
+          </label>
+        <% end %>
+        <p class="open-blog-read-warning mt-2 text-sm text-amber-800">Without read, this token cannot list or fetch posts.</p>
+      </fieldset>
+
+      <div>
+        <%= form.label :expires_at, "Expires at (#{Time.zone.name})", class: "block text-sm font-medium text-slate-700" %>
+        <%= form.datetime_local_field :expires_at, value: @expires_at, required: !no_expiry_allowed?, class: "form-input mt-1" %>
+        <% if no_expiry_allowed? %>
+          <p class="mt-1 text-sm text-slate-500">Leave blank for no expiry.</p>
+        <% end %>
+      </div>
+
+      <%= form.submit "Create token", disabled: tokens_inactive?, class: "px-4 py-2 rounded-lg bg-slate-900 text-white text-sm font-medium" %>
+    <% end %>
+  </div>
+</div>

data/app/views/open_blog/admin_suite/api_tokens/revealed.html.erb

@@ -0,0 +1,30 @@
+<% content_for :title, "API token created - Admin Suite" %>
+<% content_for :head do %>
+  <meta name="turbo-cache-control" content="no-cache">
+<% end %>
+
+<div class="px-4 sm:px-6 lg:px-8 max-w-3xl mx-auto">
+  <h1 class="text-2xl font-bold text-slate-900 mb-6"><%= @token.name %></h1>
+
+  <div class="bg-white rounded-xl border border-amber-300 p-6 space-y-4">
+    <p class="text-sm font-medium text-amber-900">Copy this token into your password manager now. It will not be shown again.</p>
+    <div class="flex gap-2">
+      <input id="open-blog-api-token-secret" type="text" readonly value="<%= @secret.reveal %>" autocomplete="off" spellcheck="false" class="form-input flex-1 font-mono" aria-label="API token">
+      <button type="button" id="open-blog-api-token-copy" class="px-4 py-2 rounded-lg bg-slate-900 text-white text-sm font-medium">Copy</button>
+    </div>
+    <%= javascript_tag nonce: true do %>
+      document.getElementById("open-blog-api-token-copy").addEventListener("click", function () {
+        var field = document.getElementById("open-blog-api-token-secret");
+        field.select();
+        if (navigator.clipboard) navigator.clipboard.writeText(field.value);
+      });
+    <% end %>
+    <p class="text-sm text-slate-600">Scopes: <%= @token.scopes.join(", ") %>. Expires: <%= @token.expires_at ? token_time(@token.expires_at) : "never" %>.</p>
+    <% if @predecessor %>
+      <p class="text-sm font-medium text-slate-900">
+        <%= @predecessor.revoked_at ? "The previous token stopped working now." : "The previous token stops working at #{token_time(@predecessor.expires_at)}." %>
+      </p>
+    <% end %>
+    <p class="text-sm"><%= link_to "Back to API tokens", open_blog_api_tokens_path %></p>
+  </div>
+</div>

data/app/views/open_blog/admin_suite/api_tokens/show.html.erb

@@ -0,0 +1,80 @@
+<% content_for :title, "API token - Admin Suite" %>
+
+<div class="px-4 sm:px-6 lg:px-8 max-w-4xl mx-auto">
+  <nav class="mb-2 text-sm text-slate-500"><%= link_to "API tokens", open_blog_api_tokens_path %></nav>
+  <h1 class="text-2xl font-bold text-slate-900 mb-6"><%= @token.name %></h1>
+
+  <%= render "error" %>
+
+  <div class="bg-white rounded-xl border border-slate-200 p-6 mb-6">
+    <dl class="grid grid-cols-2 gap-4 text-sm">
+      <dt class="text-slate-500">Prefix</dt><dd class="font-mono"><%= @token.token_prefix %></dd>
+      <dt class="text-slate-500">Scopes</dt><dd><%= @token.scopes.join(", ") %></dd>
+      <dt class="text-slate-500">Owner</dt><dd><%= @token.creator_identity || "No owner" %></dd>
+      <dt class="text-slate-500">Status</dt><dd><%= @token.status.to_s.humanize %></dd>
+      <dt class="text-slate-500">Created</dt><dd><%= token_time(@token.created_at) %></dd>
+      <dt class="text-slate-500">Last used</dt><dd><%= @token.last_used_at ? token_time(@token.last_used_at) : "Never" %></dd>
+      <dt class="text-slate-500">Expires</dt><dd><%= @token.expires_at ? token_time(@token.expires_at) : "Never" %></dd>
+      <% if @token.revoked_at %>
+        <dt class="text-slate-500">Revoked</dt><dd><%= token_time(@token.revoked_at) %></dd>
+      <% end %>
+      <% if @token.successor_id %>
+        <dt class="text-slate-500">Replaced by</dt><dd><%= link_to "Token #{@token.successor_id}", open_blog_api_token_path(@token.successor_id) %></dd>
+      <% end %>
+    </dl>
+  </div>
+
+  <% if @token.status == :active %>
+    <div class="grid gap-6 md:grid-cols-2 mb-6">
+      <% if @token.successor_id.nil? && @token.creator_identity == @identity && grant.manage_own && !tokens_inactive? %>
+        <div class="bg-white rounded-xl border border-slate-200 p-6">
+          <h2 class="text-lg font-semibold text-slate-900 mb-2">Rotate</h2>
+          <p class="text-sm text-slate-600 mb-4">Rotation issues a replacement with the same name and scopes. Without grace, this token stops working at once.</p>
+          <%= form_with url: rotate_open_blog_api_token_path(@token), method: :post, data: { turbo: false }, class: "space-y-4" do |form| %>
+            <div>
+              <%= form.label :grace, "Grace period", class: "block text-sm font-medium text-slate-700" %>
+              <%= form.select :grace, grace_options, {}, class: "form-select mt-1" %>
+            </div>
+            <label class="flex items-center gap-2 text-sm">
+              <%= check_box_tag :confirm, "1", false, id: "rotate_confirm" %>
+              I understand clients using this token must switch to the replacement.
+            </label>
+            <%= form.submit "Rotate token", class: "px-4 py-2 rounded-lg bg-slate-900 text-white text-sm font-medium" %>
+          <% end %>
+        </div>
+      <% end %>
+      <% if @token.revoked_at.nil? %>
+        <div class="bg-white rounded-xl border border-red-200 p-6">
+          <h2 class="text-lg font-semibold text-slate-900 mb-2">Revoke</h2>
+          <p class="text-sm text-slate-600 mb-4">Revoking stops this token at once. This cannot be undone.</p>
+          <%= form_with url: revoke_open_blog_api_token_path(@token), method: :post, data: { turbo: false }, class: "space-y-4" do |form| %>
+            <label class="flex items-center gap-2 text-sm">
+              <%= check_box_tag :confirm, "1", false, id: "revoke_confirm" %>
+              I understand clients using this token will stop working.
+            </label>
+            <%= form.submit "Revoke token", class: "px-4 py-2 rounded-lg bg-red-600 text-white text-sm font-medium" %>
+          <% end %>
+        </div>
+      <% end %>
+    </div>
+  <% end %>
+
+  <div class="bg-white rounded-xl border border-slate-200 p-6">
+    <h2 class="text-lg font-semibold text-slate-900 mb-4">Events</h2>
+    <table class="min-w-full text-sm">
+      <thead class="text-left text-slate-600">
+        <tr><th class="py-2 pr-4">Action</th><th class="py-2 pr-4">Actor</th><th class="py-2 pr-4">Time</th><th class="py-2">Details</th></tr>
+      </thead>
+      <tbody class="divide-y divide-slate-100">
+        <% @token.events.order(:created_at, :id).each do |event| %>
+          <tr>
+            <td class="py-2 pr-4"><%= event.action %></td>
+            <td class="py-2 pr-4"><%= event.actor_identity %></td>
+            <td class="py-2 pr-4"><%= token_time(event.created_at) %></td>
+            <td class="py-2 font-mono text-xs"><%= (event.details || {}).map { |key, value| "#{key}: #{Array(value).join(", ")}" }.join("; ") %></td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+</div>

data/db/migrate/20261029120000_add_open_blog_api_token_management.rb

@@ -0,0 +1,18 @@
+class AddOpenBlogApiTokenManagement < ActiveRecord::Migration[8.0]
+  def change
+    key_type = connection.columns(:open_blog_api_tokens).find { |column| column.name == "id" }.type == :uuid ? :uuid : :bigint
+
+    change_table :open_blog_api_tokens do |t|
+      t.string :creator_identity, index: true
+      t.references :successor, type: key_type, index: { unique: true }, foreign_key: { to_table: :open_blog_api_tokens }
+    end
+
+    create_table :open_blog_api_token_events do |t|
+      t.references :api_token, type: key_type, null: false, index: true, foreign_key: { to_table: :open_blog_api_tokens }
+      t.string :actor_identity, null: false
+      t.string :action, null: false
+      t.public_send(connection.adapter_name == "PostgreSQL" ? :jsonb : :json, :details, null: false, default: {})
+      t.datetime :created_at, null: false
+    end
+  end
+end

data/lib/generators/open_blog/admin_suite/admin_suite_generator.rb

@@ -20,7 +20,10 @@ module OpenBlog
         end
         template "blog_portal.rb.tt", "#{@admin_dir}/portals/open_blog_portal.rb", **copy_options
         template "initializer.rb.tt", "config/initializers/open_blog_admin_suite.rb", **copy_options
+        template "api_tokens_initializer.rb.tt", "config/initializers/open_blog_api_tokens.rb", **copy_options
+        template "open_blog.yml.tt", "config/open_blog.yml", **copy_options
         say "Admin definitions written. Install AdminSuite 0.6.1 or later to activate them; restart the host after adding definitions."
+        say "API tokens stay disabled until config.api_tokens.identity returns a trusted admin identity and config/open_blog.yml grants it access."
       end
     end
   end

data/lib/generators/open_blog/admin_suite/templates/api_tokens_initializer.rb.tt

@@ -0,0 +1,9 @@
+OpenBlog.configure do |config|
+  config.api_tokens.policy = OpenBlog::ApiTokens::YamlGrants.load(Rails.root.join("config/open_blog.yml"))
+  # Bind to the admin surface identity, never an application login fallback.
+  # config.api_tokens.identity = ->(controller) { admin = controller.send(:current_admin); "admin:#{admin.uid}" if admin }
+  config.api_tokens.default_lifetime = 90.days
+  config.api_tokens.require_expiry = false
+  config.api_tokens.max_lifetime = nil
+  config.api_tokens.max_grace = 24.hours
+end

data/lib/generators/open_blog/admin_suite/templates/open_blog.yml.tt

@@ -0,0 +1,2 @@
+api_tokens:
+  grants: {}

data/lib/open_blog/admin_suite/api_tokens_controller.rb

@@ -0,0 +1,150 @@
+module OpenBlog
+  module AdminSuite
+    class ApiTokensController < ::AdminSuite::ApplicationController
+      include ::AdminSuite::Engine.routes.url_helpers
+
+      GRACES = { "none" => nil, "3600" => 1.hour, "86400" => 24.hours }.freeze
+      ERRORS = {
+        invalid: "Check the name and choose at least one scope.",
+        scope_not_allowed: "One of those scopes is not allowed for you.",
+        expiry_invalid: "Choose an expiry the token policy allows.",
+        grace_invalid: "Choose a grace period from the list.",
+        not_rotatable: "Only an active token with an owner can be rotated.",
+        already_rotated: "This token was already rotated.",
+        tokens_inactive: "This host uses its own API authentication hook. Tokens issued here would not work.",
+        unauthorized: "You cannot do that with this token."
+      }.freeze
+
+      protect_from_forgery with: :exception, prepend: true
+      before_action :require_grant
+
+      helper_method :grant, :tokens_inactive?, :grace_options, :no_expiry_allowed?, :token_time
+
+      def index
+        @tokens = ApiTokens.list(identity: @identity).tokens
+      end
+
+      def new
+        return forbidden(ERRORS[:unauthorized]) unless grant.manage_own
+        @scopes = grant.scopes.include?("read") ? %w[read] : []
+        @expires_at = ApiTokens.default_expires_at.strftime("%Y-%m-%dT%H:%M")
+      end
+
+      def create
+        @scopes = params[:scopes].is_a?(Array) ? params[:scopes].map(&:to_s) : []
+        @expires_at = params[:expires_at].is_a?(String) ? params[:expires_at] : ""
+        expires_at = parse_expiry(@expires_at)
+        return render_new(:expiry_invalid) if expires_at == :invalid
+        name = params[:name].is_a?(String) ? params[:name] : ""
+        result = ApiTokens.issue(identity: @identity, name: name, scopes: @scopes, expires_at: expires_at)
+        return reveal(result) if result.success?
+        return forbidden(ERRORS[:unauthorized]) if result.error == :unauthorized
+        render_new(result.error)
+      end
+
+      def show
+        result = ApiTokens.find(identity: @identity, id: params[:id])
+        return failed(result) unless result.success?
+        @token = result.token
+      end
+
+      def revoke
+        return unless confirmed?
+        result = ApiTokens.revoke(identity: @identity, id: params[:id])
+        return failed(result) unless result.success?
+        redirect_to open_blog_api_token_path(result.token), notice: "Token revoked."
+      end
+
+      def rotate
+        return unless confirmed?
+        return render_show(ERRORS[:grace_invalid]) unless grace_options.value?(params[:grace].to_s)
+        result = ApiTokens.rotate(identity: @identity, id: params[:id], grace: GRACES[params[:grace].to_s])
+        return failed(result) unless result.success?
+        @predecessor = result.token.predecessor
+        reveal(result)
+      end
+
+      private
+
+      def grant
+        @grant
+      end
+
+      def require_grant
+        @identity = OpenBlog.config.api_tokens.identity&.call(self)
+        return forbidden("No trusted identity is configured for API token management.") if @identity.nil?
+        @grant = ApiTokens.permissions(identity: @identity)
+        forbidden("No token-management grant for this identity.") unless @grant && (@grant.manage_own || @grant.manage_all)
+      end
+
+      def token_time(time)
+        "#{time.in_time_zone.strftime('%Y-%m-%d %H:%M:%S')} (#{Time.zone.name})"
+      end
+
+      def tokens_inactive?
+        OpenBlog.config.authenticate ? true : false
+      end
+
+      def no_expiry_allowed?
+        settings = OpenBlog.config.api_tokens
+        !settings.require_expiry && settings.max_lifetime.nil?
+      end
+
+      def grace_options
+        max = OpenBlog.config.api_tokens.max_grace.to_f
+        { "No grace (revoke now)" => "none", "1 hour" => "3600", "24 hours" => "86400" }
+          .select { |_label, value| GRACES[value].nil? || GRACES[value].to_f <= max }
+      end
+
+      def parse_expiry(value)
+        return if value.strip.empty?
+        Time.zone.parse(value) || :invalid
+      rescue ArgumentError
+        :invalid
+      end
+
+      def confirmed?
+        return true if params[:confirm] == "1"
+        render_show("Tick the confirmation box to continue.")
+        false
+      end
+
+      def reveal(result)
+        no_store
+        @token = result.token
+        @secret = result.secret
+        render :revealed, status: :ok
+      end
+
+      def render_new(error)
+        @error = ERRORS.fetch(error, ERRORS[:invalid])
+        render :new, status: :unprocessable_content
+      end
+
+      def render_show(message)
+        @token ||= ApiTokens.find(identity: @identity, id: params[:id]).token
+        return not_found unless @token
+        @error = message
+        render :show, status: :unprocessable_content
+      end
+
+      def failed(result)
+        case result.error
+        when :not_found then not_found
+        when :unauthorized then forbidden(ERRORS[:unauthorized])
+        else render_show(ERRORS.fetch(result.error, ERRORS[:invalid]))
+        end
+      end
+
+      def forbidden(message)
+        @message = message
+        render :error, status: :forbidden
+      end
+
+      def not_found
+        @message = "No such token."
+        render :error, status: :not_found
+      end
+    end
+  end
+end

data/lib/open_blog/admin_suite.rb

@@ -38,19 +38,57 @@ module OpenBlog
       end
     end
 
+    module Navigation
+      private
+
+      def build_navigation_items
+        navigation = super
+        portal = navigation[:open_blog] ||= { label: "Open Blog", order: 100, sections: {} }
+        portal[:sections] ||= {}
+        section = portal[:sections][:access] ||= { label: "Access", order: 900, items: [] }
+        section[:items] << { label: "API tokens", path: open_blog_api_tokens_path, icon: "key", order: 900 }
+        navigation
+      end
+    end
+
     def self.install!
       return if @installed
       ::AdminSuite::UI::FieldRendererRegistry.register(:open_blog_faq) do |view, form, field, resource, field_class|
         render_faqs(view, form, field, resource, field_class)
       end
+      install_routes!
       Rails.application.reloader.to_prepare { ::OpenBlog::AdminSuite.install_controller! }
       install_controller!
       @installed = true
     end
 
+    # The prepended block runs at the start of every draw, so reloads redraw it once
+    # instead of stacking copies. Hosts that already drew routes need one redraw.
+    def self.install_routes!
+      ::AdminSuite::Engine.routes.prepend { ::OpenBlog::AdminSuite.draw_routes(self) }
+      Rails.application.reload_routes! if Rails.application.routes_reloader.loaded
+    end
+
+    def self.draw_routes(mapper)
+      controller = "/open_blog/admin_suite/api_tokens"
+      mapper.scope "open_blog/api_tokens", controller: controller do
+        mapper.get "/", action: :index, as: :open_blog_api_tokens
+        mapper.post "/", action: :create
+        mapper.get "/new", action: :new, as: :new_open_blog_api_token
+        mapper.get "/:id", action: :show, as: :open_blog_api_token
+        mapper.post "/:id/revoke", action: :revoke, as: :revoke_open_blog_api_token
+        mapper.post "/:id/rotate", action: :rotate, as: :rotate_open_blog_api_token
+      end
+    end
+
     def self.install_controller!
       controller = ::AdminSuite::ResourcesController
       controller.prepend(ResourceParameters) unless controller.ancestors.include?(ResourceParameters)
+      base = ::AdminSuite::ApplicationController
+      base.prepend(Navigation) unless base.ancestors.include?(Navigation)
+      return if const_defined?(:ApiTokensController, false) && ApiTokensController.superclass.equal?(base)
+      remove_const(:ApiTokensController) if const_defined?(:ApiTokensController, false)
+      load File.expand_path("admin_suite/api_tokens_controller.rb", __dir__)
     end
 
     def self.render_faqs(view, form, field, resource, field_class)

data/lib/open_blog/api_tokens/grant.rb

@@ -0,0 +1,12 @@
+module OpenBlog
+  module ApiTokens
+    SCOPES = %w[read write publish].freeze
+    IDENTITY = /\A[a-z0-9_]+:\S{1,200}\z/
+
+    Grant = Data.define(:manage_own, :manage_all, :scopes) do
+      def initialize(manage_own:, manage_all:, scopes:)
+        super(manage_own:, manage_all:, scopes: scopes.map(&:to_s).freeze)
+      end
+    end
+  end
+end

data/lib/open_blog/api_tokens/result.rb

@@ -0,0 +1,13 @@
+module OpenBlog
+  module ApiTokens
+    Result = Data.define(:token, :tokens, :secret, :error, :details) do
+      def initialize(token: nil, tokens: [], secret: nil, error: nil, details: [])
+        super
+      end
+
+      def success?
+        error.nil?
+      end
+    end
+  end
+end

data/lib/open_blog/api_tokens/secret.rb

@@ -0,0 +1,33 @@
+require "json"
+
+module OpenBlog
+  module ApiTokens
+    class Secret
+      FILTERED = "[FILTERED]".freeze
+
+      def initialize(value)
+        @value = value.dup.freeze
+      end
+
+      def reveal
+        @value
+      end
+
+      def to_s
+        FILTERED
+      end
+
+      def inspect
+        FILTERED
+      end
+
+      def as_json(*)
+        FILTERED
+      end
+
+      def to_json(*)
+        FILTERED.to_json
+      end
+    end
+  end
+end

data/lib/open_blog/api_tokens/yaml_grants.rb

@@ -0,0 +1,67 @@
+require "yaml"
+require "open_blog/configuration_error"
+require "open_blog/api_tokens/grant"
+
+module OpenBlog
+  module ApiTokens
+    class YamlGrants
+      MANAGE_LEVELS = %w[own all].freeze
+
+      def self.load(path)
+        return new({}) unless File.exist?(path)
+
+        document = YAML.safe_load_file(path)
+        new(parse(document, path))
+      rescue Psych::Exception => error
+        raise ConfigurationError, "OpenBlog api_tokens grants #{path} is not valid YAML: #{error.message}"
+      end
+
+      def self.parse(document, path)
+        return {} if document.nil?
+        fail_with(path, "must be a mapping") unless document.is_a?(Hash)
+        unknown = document.keys - [ "api_tokens" ]
+        fail_with(path, "has unknown top-level keys: #{unknown.join(', ')}") if unknown.any?
+        section = document["api_tokens"]
+        return {} if section.nil?
+        fail_with(path, "api_tokens must be a mapping") unless section.is_a?(Hash)
+        unknown = section.keys - [ "grants" ]
+        fail_with(path, "api_tokens has unknown keys: #{unknown.join(', ')}") if unknown.any?
+        grants = section["grants"]
+        return {} if grants.nil?
+        fail_with(path, "grants must be a mapping") unless grants.is_a?(Hash)
+        grants.to_h { |identity, grant| [ identity, build_grant(identity, grant, path) ] }
+      end
+      private_class_method :parse
+
+      def self.build_grant(identity, grant, path)
+        fail_with(path, "grant key #{identity.inspect} must match #{IDENTITY.source}") unless identity.is_a?(String) && identity.match?(IDENTITY)
+        fail_with(path, "grant #{identity} must be a mapping") unless grant.is_a?(Hash)
+        unknown = grant.keys - %w[manage scopes]
+        fail_with(path, "grant #{identity} has unknown keys: #{unknown.join(', ')}") if unknown.any?
+        manage = Array(grant["manage"]).map(&:to_s)
+        fail_with(path, "grant #{identity} manage must be own or all") unless (manage - MANAGE_LEVELS).empty?
+        scopes = Array(grant["scopes"]).map(&:to_s)
+        fail_with(path, "grant #{identity} scopes must be within #{SCOPES.join(', ')}") unless (scopes - SCOPES).empty?
+        Grant.new(manage_own: manage.include?("own"), manage_all: manage.include?("all"), scopes: scopes.uniq)
+      end
+      private_class_method :build_grant
+
+      def self.fail_with(path, message)
+        raise ConfigurationError, "OpenBlog api_tokens grants #{path} #{message}"
+      end
+      private_class_method :fail_with
+
+      def initialize(grants)
+        @grants = grants.freeze
+      end
+
+      def grants_for(identity)
+        @grants[identity]
+      end
+
+      def empty?
+        @grants.empty?
+      end
+    end
+  end
+end

data/lib/open_blog/api_tokens.rb

@@ -0,0 +1,146 @@
+require_relative "api_tokens/grant"
+require_relative "api_tokens/result"
+require_relative "api_tokens/secret"
+
+module OpenBlog
+  module ApiTokens
+    NAME_LENGTH = 1..100
+
+    class << self
+      def permissions(identity:)
+        return unless identity.is_a?(String) && identity.match?(IDENTITY)
+        grant = settings.policy&.grants_for(identity)
+        grant if grant.is_a?(Grant)
+      end
+
+      def default_expires_at(now: Time.current)
+        [ now + settings.default_lifetime, settings.max_lifetime && now + settings.max_lifetime ].compact.min
+      end
+
+      def list(identity:)
+        authorize(identity) do |grant|
+          Result.new(tokens: visible(identity, grant).order(created_at: :desc, id: :desc).to_a)
+        end
+      end
+
+      def find(identity:, id:)
+        authorize(identity) do |grant|
+          token = visible(identity, grant).find_by(id: id)
+          token ? Result.new(token: token) : failure(:not_found)
+        end
+      end
+
+      def issue(identity:, name:, scopes:, expires_at:, now: Time.current)
+        authorize(identity) do |grant|
+          next failure(:unauthorized) unless grant.manage_own
+          next failure(:tokens_inactive) if OpenBlog.config.authenticate
+          name = name.strip if name.is_a?(String)
+          scopes = scopes.map(&:to_s) if scopes.is_a?(Array)
+          invalid = []
+          invalid << "name" unless name.is_a?(String) && NAME_LENGTH.cover?(name.length)
+          invalid << "scopes" unless valid_scopes?(scopes)
+          next failure(:invalid, invalid) if invalid.any?
+          next failure(:scope_not_allowed) unless (scopes - grant.scopes).empty?
+          next failure(:expiry_invalid) unless valid_expiry?(expires_at, now)
+          ApiToken.transaction { create_token(identity, name, scopes, expires_at) }
+        end
+      end
+
+      def revoke(identity:, id:, now: Time.current)
+        authorize(identity) do |grant|
+          token = visible(identity, grant).find_by(id: id)
+          next failure(:not_found) unless token
+          ApiToken.transaction do
+            if ApiToken.where(id: token.id, revoked_at: nil).update_all(revoked_at: now, updated_at: now) == 1
+              record_event(token, identity, "revoked", {})
+            end
+            Result.new(token: token.reload)
+          end
+        end
+      end
+
+      def rotate(identity:, id:, grace: nil, now: Time.current)
+        authorize(identity) do |grant|
+          next failure(:tokens_inactive) if OpenBlog.config.authenticate
+          token = visible(identity, grant).find_by(id: id)
+          next failure(:not_found) unless token
+          next failure(:not_rotatable) if token.creator_identity.nil?
+          next failure(:unauthorized) unless token.creator_identity == identity && grant.manage_own
+          next failure(:grace_invalid) unless grace.nil? || valid_grace?(grace)
+          ApiToken.transaction(requires_new: true) do
+            rotate_locked(ApiToken.lock.find(token.id), identity, grant, grace, now)
+          end || failure(:already_rotated)
+        end
+      end
+
+      private
+
+      def settings
+        OpenBlog.config.api_tokens
+      end
+
+      def authorize(identity)
+        grant = permissions(identity: identity)
+        return failure(:unauthorized) unless grant && (grant.manage_own || grant.manage_all)
+        yield grant
+      end
+
+      def visible(identity, grant)
+        grant.manage_all ? ApiToken.all : ApiToken.where(creator_identity: identity)
+      end
+
+      def failure(error, details = [])
+        Result.new(error: error, details: details)
+      end
+
+      def valid_scopes?(scopes)
+        scopes.is_a?(Array) && scopes.any? && scopes.uniq.size == scopes.size && (scopes - SCOPES).empty?
+      end
+
+      def valid_expiry?(expires_at, now)
+        max = settings.max_lifetime
+        return !settings.require_expiry && max.nil? if expires_at.nil?
+        return false unless expires_at.is_a?(Time) || expires_at.is_a?(DateTime)
+        expires_at > now && (max.nil? || expires_at <= now + max)
+      end
+
+      def valid_grace?(grace)
+        (grace.is_a?(Numeric) || grace.is_a?(ActiveSupport::Duration)) && grace.to_f.finite? &&
+          grace.to_f.positive? && grace.to_f <= settings.max_grace.to_f
+      end
+
+      def create_token(identity, name, scopes, expires_at, **details)
+        token, secret = ApiToken.generate(name: name, scopes: scopes, expires_at: expires_at, creator_identity: identity)
+        record_event(token, identity, "issued", { scopes: scopes, expires_at: expires_at&.iso8601, **details })
+        Result.new(token: token, secret: Secret.new(secret))
+      end
+
+      # sqlite ignores FOR UPDATE, so the guarded update_all is what keeps one successor
+      # per token. Losing that race raises Rollback, which needs the requires_new savepoint.
+      def rotate_locked(old, identity, grant, grace, now)
+        return failure(:already_rotated) if old.successor_id
+        return failure(:not_rotatable) unless old.revoked_at.nil? && (old.expires_at.nil? || old.expires_at > now)
+        return failure(:scope_not_allowed) unless (old.scopes - grant.scopes).empty?
+
+        cutoff = grace ? [ old.expires_at, now + grace ].compact.min : now
+        replacement = create_token(identity, old.name, old.scopes, default_expires_at(now: now), predecessor_id: old.id)
+        changes = grace ? { expires_at: cutoff } : { revoked_at: now }
+        claimed = begin
+          ApiToken.where(id: old.id, successor_id: nil, revoked_at: nil)
+            .update_all(changes.merge(successor_id: replacement.token.id, updated_at: now))
+        rescue ActiveRecord::RecordNotUnique
+          0
+        end
+        raise ActiveRecord::Rollback unless claimed == 1
+
+        record_event(old, identity, "rotated", { successor_id: replacement.token.id, old_expires_at: old.expires_at&.iso8601,
+          new_cutoff: cutoff.iso8601, revoked: grace.nil? })
+        replacement
+      end
+
+      def record_event(token, identity, action, details)
+        ApiTokenEvent.create!(api_token: token, actor_identity: identity, action: action, details: details)
+      end
+    end
+  end
+end

data/lib/open_blog/authentication.rb

@@ -12,7 +12,10 @@ module OpenBlog
       match = /\ABearer (ob_[1-9A-HJ-NP-Za-km-z]{40})\z/.match(request.authorization.to_s)
       return unless match
       token = ApiToken.authenticate(match[1])
-      Actor.new(name: token.name, scopes: token.scopes, id: "token:#{token.id}") if token
+      return unless token
+      owner = token.has_attribute?(:creator_identity) && token.creator_identity.presence
+      name = owner ? "#{token.name} (#{owner})" : token.name
+      Actor.new(name: name, scopes: token.scopes, id: "token:#{token.id}")
     end
   end
 end

data/lib/open_blog/configuration.rb

@@ -18,6 +18,23 @@ module OpenBlog
       end
     end
 
+    class ApiTokens
+      attr_reader :identity
+      attr_accessor :policy, :default_lifetime, :require_expiry, :max_lifetime, :max_grace
+
+      def initialize
+        @default_lifetime = 90.days
+        @require_expiry = false
+        @max_lifetime = nil
+        @max_grace = 24.hours
+      end
+
+      def identity=(hook)
+        Configuration.validate_hook!(:identity, hook, 1)
+        @identity = hook
+      end
+    end
+
     THEMES = (Themes.names + [ :none ]).freeze
     THEME_MODES = %i[light dark].freeze
     THEME_COLOR_KEYS = Themes::COLOR_TOKENS.to_h { |token| [ token.tr("-", "_").to_sym, token ] }.freeze
@@ -31,7 +48,7 @@ module OpenBlog
       :page_views, :page_view_bot_pattern, :page_view_retention_days, :popular_posts,
       :preview_expires_in, :storage_service, :image_delivery, :max_image_bytes,
       :image_content_types, :image_fetch_policy, :api_rate_limit, :search_rate_limit
-    attr_reader :mcp, :authenticate, :before_publish
+    attr_reader :mcp, :api_tokens, :authenticate, :before_publish
     attr_writer :title_suffix, :rate_limit_store
 
     def initialize
@@ -68,6 +85,7 @@ module OpenBlog
       @api_rate_limit = { to: 120, within: 1.minute }
       @search_rate_limit = { to: 30, within: 1.minute }
       @mcp = Mcp.new
+      @api_tokens = ApiTokens.new
     end
 
     def title_suffix
@@ -113,6 +131,7 @@ module OpenBlog
       validate_view_settings!
       invalid!(:mcp, "enabled must be true or false") unless [ true, false ].include?(mcp.enabled)
       invalid!(:mcp, "max_page_size must be a positive integer") unless mcp.max_page_size.is_a?(Integer) && mcp.max_page_size.positive?
+      validate_api_tokens!
       self
     end
 
@@ -131,8 +150,37 @@ module OpenBlog
       end
     end
 
+    def self.validate_hook!(name, hook, argument_count)
+      return if hook.nil?
+      raise ConfigurationError, "OpenBlog #{name} must be callable" unless hook.respond_to?(:call)
+      parameters = hook.is_a?(Proc) || hook.is_a?(Method) ? hook.parameters : hook.method(:call).parameters
+      required = parameters.count { |kind, _| kind == :req }
+      capacity = parameters.count { |kind, _| %i[req opt].include?(kind) }
+      rest = parameters.any? { |kind, _| kind == :rest }
+      keywords = parameters.any? { |kind, _| kind == :keyreq }
+      unless required <= argument_count && (rest || capacity >= argument_count) && !keywords
+        raise ConfigurationError, "OpenBlog #{name} must accept #{argument_count} positional arguments without required keywords"
+      end
+    end
+
     private
 
+    def validate_api_tokens!
+      settings = api_tokens
+      Configuration.validate_hook!(:identity, settings.identity, 1)
+      invalid!("api_tokens.policy", "must respond to grants_for") unless settings.policy.nil? || settings.policy.respond_to?(:grants_for)
+      invalid!("api_tokens.require_expiry", "must be true or false") unless [ true, false ].include?(settings.require_expiry)
+      { default_lifetime: false, max_lifetime: true, max_grace: false }.each do |key, nullable|
+        value = settings.public_send(key)
+        next if nullable && value.nil?
+        positive_finite = (value.is_a?(Numeric) || value.is_a?(ActiveSupport::Duration)) && value.to_f.finite? && value.to_f.positive?
+        invalid!("api_tokens.#{key}", "must be a positive finite duration") unless positive_finite
+      end
+      if settings.max_lifetime && settings.max_lifetime.to_f < settings.default_lifetime.to_f
+        invalid!("api_tokens.max_lifetime", "must be at least default_lifetime")
+      end
+    end
+
     def validate_theme!
       invalid!(:theme, "must be #{THEMES.map(&:inspect).join(', ')}") unless THEMES.include?(theme)
       invalid!(:faq_collapsed, "must be true or false") unless [ true, false ].include?(faq_collapsed)
@@ -202,16 +250,7 @@ module OpenBlog
     end
 
     def validate_hook!(name, hook, argument_count)
-      return if hook.nil?
-      invalid!(name, "must be callable") unless hook.respond_to?(:call)
-      parameters = hook.is_a?(Proc) || hook.is_a?(Method) ? hook.parameters : hook.method(:call).parameters
-      required = parameters.count { |kind, _| kind == :req }
-      capacity = parameters.count { |kind, _| %i[req opt].include?(kind) }
-      rest = parameters.any? { |kind, _| kind == :rest }
-      keywords = parameters.any? { |kind, _| kind == :keyreq }
-      unless required <= argument_count && (rest || capacity >= argument_count) && !keywords
-        invalid!(name, "must accept #{argument_count} positional arguments without required keywords")
-      end
+      Configuration.validate_hook!(name, hook, argument_count)
     end
 
     def invalid!(name, message)

data/lib/open_blog/doctor.rb

@@ -11,6 +11,7 @@ module OpenBlog
 
     CHECKS = { "Configuration" => :configuration, "Migrations" => :migrations, "Route" => :route,
       "Views" => :views, "Theme" => :theme, "JavaScript" => :javascript, "Authentication" => :authentication,
+      "API token management" => :api_token_management,
       "Rate limit" => :rate_limit, "Jobs" => :jobs, "Storage" => :storage, "Record keys" => :record_keys, "Policy pages" => :policy_pages,
       "Records" => :records, "Declarations" => :declarations }.freeze
     TABLES = %w[open_blog_authors open_blog_categories open_blog_series open_blog_images open_blog_posts
@@ -86,6 +87,21 @@ module OpenBlog
       end
     end
 
+    def api_token_management
+      return [ "ok", "AdminSuite is not installed." ] unless defined?(OpenBlog::AdminSuite)
+      settings = @config.api_tokens
+      policy = settings.policy
+      problems = []
+      problems << "No identity hook: set config.api_tokens.identity." unless settings.identity
+      if policy.nil?
+        problems << "No grant policy: set config.api_tokens.policy."
+      elsif policy.respond_to?(:empty?) && policy.empty?
+        problems << "No grants: add an identity under api_tokens.grants in config/open_blog.yml."
+      end
+      problems << "Tokens inactive: config.authenticate is set, so the API ignores tokens." if @config.authenticate
+      problems.any? ? [ "warning", problems.join(" ") ] : [ "ok", "Token management is wired to a host identity and grants." ]
+    end
+
     def rate_limit
       key = "open-blog-doctor-#{SecureRandom.hex(12)}"
       store = @config.rate_limit_store

data/lib/open_blog/version.rb

@@ -1,3 +1,3 @@
 module OpenBlog
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/open_blog.rb

@@ -6,6 +6,9 @@ require "mcp"
 
 require_relative "open_blog/version"
 require_relative "open_blog/instructions"
+require_relative "open_blog/api_tokens/grant"
+require_relative "open_blog/api_tokens/yaml_grants"
+require_relative "open_blog/api_tokens"
 
 module OpenBlog
   FAQ_SELECTORS = { section: "[data-open-blog-faq]", entry: "[data-open-blog-faq-entry]" }.freeze

data/skills/open-blog-install/SKILL.md

@@ -45,6 +45,23 @@ Place a single theme button in the shared navbar if requested; it is not a separ
 
 The controller stores `open-blog-theme` and sets `data-theme="light"` or `"dark"` on `<html>`; System removes both and follows the OS. Restore that same key before CSS loads on homepage and blog using the gem helper or one shared equivalent script with the host's CSP nonce. Keep one preference owner when the host already has a theme controller. Honor a fixed `config.color_scheme` by retaining its root attribute and omitting the toggle. Check Turbo transitions if used, full reloads, explicit light/dark, and system mode.
 
+## Wire API token management
+
+Do this read-only discovery before asking questions or writing. Cite file evidence, and separate local checkout findings from deployed state.
+
+1. Read host instructions; note Open Blog and AdminSuite versions and existing customizations.
+2. Find the admin mount, its authentication, the trusted actor, stable identifiers, and whether user and admin sessions are separate.
+3. Find real authorization hooks, permission or role models, and tenant boundaries. Never treat roles as equivalent by name.
+4. Read any `config.api_tokens` settings and the API authentication mode (`config.authenticate` makes tokens inactive). Never retrieve or print stored credentials.
+5. Propose the smallest integration: `bin/rails generate open_blog:admin_suite`, an `api_tokens.identity` bound to the admin identity, and grants.
+6. Ask only unresolved policy questions: who gets own or all, which scopes, expiry rules, grace. Technical capability is not approval to grant.
+7. Prefer an existing permission system as `api_tokens.policy`; otherwise propose stable-identity grants in `config/open_blog.yml`. Get approval before real grants.
+8. Get installation authorization before writes. Deployment and production token issuance are separate permissions.
+9. In an authorized local or test environment, verify allowed and denied access, ownership isolation, scope limits, expiry, rotation, one-time reveal, audit secrecy, and that a rerun keeps edited files.
+10. Report verified behavior, blockers, and unverified production assumptions separately.
+
+Do not recommend ECS stdout issuance, encryption wrappers, or temporary-file delivery as the recurring workflow.
+
 ## Upgrade copied files deliberately
 
 Read the target changelog, update any version constraint, then `bundle update open_blog --conservative`; review dependency changes too (on Rails 8.0, keep JSON below 3; Rails 8.1 can use JSON 3). Bundler does not refresh copied host files.

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: open_blog
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - TechWright Labs
 bindir: bin
 cert_chain: []
-date: 2026-10-28 00:00:00.000000000 Z
+date: 2026-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -309,6 +309,7 @@ files:
 - app/models/concerns/open_blog/immutable_image_attachment.rb
 - app/models/concerns/open_blog/previewable.rb
 - app/models/open_blog/api_token.rb
+- app/models/open_blog/api_token_event.rb
 - app/models/open_blog/application_record.rb
 - app/models/open_blog/approval.rb
 - app/models/open_blog/author.rb
@@ -343,6 +344,13 @@ files:
 - app/serializers/open_blog/series_serializer.rb
 - app/serializers/open_blog/tag_serializer.rb
 - app/serializers/open_blog/write_result_serializer.rb
+- app/views/open_blog/admin_suite/api_tokens/_banner.html.erb
+- app/views/open_blog/admin_suite/api_tokens/_error.html.erb
+- app/views/open_blog/admin_suite/api_tokens/error.html.erb
+- app/views/open_blog/admin_suite/api_tokens/index.html.erb
+- app/views/open_blog/admin_suite/api_tokens/new.html.erb
+- app/views/open_blog/admin_suite/api_tokens/revealed.html.erb
+- app/views/open_blog/admin_suite/api_tokens/show.html.erb
 - app/views/open_blog/attachments/_blob.html.erb
 - app/views/open_blog/feeds/atom.xml.builder
 - app/views/open_blog/sitemaps/show.xml.builder
@@ -366,11 +374,14 @@ files:
 - db/migrate/20261003175454_create_open_blog_pages.rb
 - db/migrate/20261003182919_create_open_blog_page_views.rb
 - db/migrate/20261020120000_align_open_blog_record_keys.rb
+- db/migrate/20261029120000_add_open_blog_api_token_management.rb
 - lib/generators/open_blog/admin_suite/admin_suite_generator.rb
+- lib/generators/open_blog/admin_suite/templates/api_tokens_initializer.rb.tt
 - lib/generators/open_blog/admin_suite/templates/author_resource.rb.tt
 - lib/generators/open_blog/admin_suite/templates/blog_portal.rb.tt
 - lib/generators/open_blog/admin_suite/templates/category_resource.rb.tt
 - lib/generators/open_blog/admin_suite/templates/initializer.rb.tt
+- lib/generators/open_blog/admin_suite/templates/open_blog.yml.tt
 - lib/generators/open_blog/admin_suite/templates/page_resource.rb.tt
 - lib/generators/open_blog/admin_suite/templates/post_resource.rb.tt
 - lib/generators/open_blog/generator_support.rb
@@ -423,10 +434,16 @@ files:
 - lib/open_blog.rb
 - lib/open_blog/actor.rb
 - lib/open_blog/admin_suite.rb
+- lib/open_blog/admin_suite/api_tokens_controller.rb
 - lib/open_blog/adopt.rb
 - lib/open_blog/adopt/contract.rb
 - lib/open_blog/adopt/snapshot.rb
 - lib/open_blog/api_fields.rb
+- lib/open_blog/api_tokens.rb
+- lib/open_blog/api_tokens/grant.rb
+- lib/open_blog/api_tokens/result.rb
+- lib/open_blog/api_tokens/secret.rb
+- lib/open_blog/api_tokens/yaml_grants.rb
 - lib/open_blog/approve.rb
 - lib/open_blog/authentication.rb
 - lib/open_blog/build_css.rb