DEV Community: Abhishek

Replacing GitHub PATs with Ephemeral Installation Tokens

Abhishek — Sun, 12 Jul 2026 07:24:31 +0000

Replacing GitHub PATs with Ephemeral Installation Tokens

Give an AI agent GitHub access without giving it a standing credential.

The problem

Every AI agent I build eventually needs to touch GitHub open an issue, push a branch, comment on a PR. And every guide, every example repo, every quickstart solves that the same way: generate a personal access token, paste it into .env,move on. I did it too, for a long time, and it always felt wrong.

A classic PAT is a standing credential. It's long-lived valid until you remember to revoke it.
It's broadly scoped it carries your whole account's reach, not the one thing the agent needs right now. And it's ambient it sits in the process environment where any code path can read it, where a stack trace can log it, and where a prompt-injected agent can be talked into exfiltrating it. Fine grained PATs help at the margins per-repo, optional expiry but they're still a credential a developer scopes by hand, pastes into an environment, and leaves lying there for weeks.

Broker isn't competing with them; it's replacing the pattern of
putting any long-lived credential where an agent can read it. The shape of the problem doesn't change: the agent is holding power it isn't using.

The idea

GitHub already has a better primitive, and almost nobody uses it for agents.

A GitHub App doesn't authenticate with a token you store. It authenticates by signing a short JWT with a private key, then exchanging that JWT for an installation access token scoped to exactly the repositories and permissions you granted the App, and expiring on GitHub's side in about an hour. Nothing to rotate. Nothing broad. Nothing that outlives the moment.

The reason people reach for a PAT anyway is ergonomics: the JWT dance, the App registration, the installation IDs it's more moving parts than "paste a token."

So I built Broker, a small capability broker that makes installation tokens the default path for an agent. The agent asks for an action; Broker checks policy, mints a token at the instant of use, spends it on one call, and logs the whole lifecycle. The agent never sees or stores a credential.

The demo

Here is the entire thesis in one screenshot. An LLM, wired to Broker over MCP, asked it to create an issue in a repository that isn't on the allowlist:

An LLM asked Broker to create an issue in a non-allowlisted repo. Broker refused.
No token was ever minted.

That last sentence is the whole point. In the PAT model, the agent already holds the credential policy is something you hope the agent respects, or something you bolt on after the fact. Here, the credential does not exist yet when the decision is made.

Policy runs first. A denial isn't "the agent was told no"; it's "there was never anything to say no with." The token for a forbidden action is never minted, never sent, never logged because Broker never reaches the mint step.

The deny path is cheaper and safer than the allow path, which is exactly the property you want in a security boundary.

Broker speaks the Model Context Protocol, which is how Claude Desktop and a growing number of agent frameworks discover and call external tools. That's what makes the demo work end-to-end: the LLM saw github_create_issue in Broker's tool catalog, chose to call it with structured parameters, and got back either a capability object or a policy denial. The interception point isn't code the developer had to write. It's the tool boundary itself.

How it works

The whole thing is three small files.

broker/policy.py is one function. It takes an action and a repo and returns a
decision — allow or deny with a reason. That's it:

def evaluate(action: str, repo: str) -> PolicyDecision:
    if action != ALLOWED_ACTION:
        return PolicyDecision(False, f"action {action} not permitted")
    if repo != ALLOWED_REPO:
        return PolicyDecision(False, f"repo {repo} not in allowlist")
    return PolicyDecision(True, "matches allowlist")

It runs before any credential exists. Wrong repo or wrong action, and the request dies here.

broker/github.py does the JWT → installation-token exchange. It signs an
RS256 JWT with the App private key (a nine-minute expiry, per GitHub's ceiling),
POSTs it to /app/installations/{id}/access_tokens, and wraps the returned token in
a Capability. The raw token goes into a private field and never leaves the object callers get a public view with the token stripped out.

broker/audit.py is json.dumps to a file. Every stage the policy decision, the mint, the use and its outcome appends one timestamped JSON line to audit.jsonl. Tokens are never written. You get a replayable, grep-able trail of who asked for what and what happened.

The difference is easiest to see in what the agent actually holds. With a PAT:

# .env — sits here for the life of the project
GITHUB_TOKEN=ghp_R8sNq...   # your whole account. no expiry. readable by any code path.

With Broker, the only thing the agent ever receives is the public capability:

{
  "id": "CAP-6AEB2D42",
  "provider": "github",
  "scope": "issues:write",
  "ttl_seconds": 3598,
  "expires_at": "2026-07-11T08:34:05Z",
  "status": "ACTIVE"
}

No secret in there. Just a receipt.

	PAT in `.env`	Broker capability
If it leaks	Full account access	An already-expiring, single-scope token
Scope	Whole account	One action (`issues:write`)
Lifetime	Months, until revoked	~1 hour, server-enforced
Storage	Sits in the environment	Never stored; minted per call

Limitations

I want to be precise about what this v0.1 is and isn't, because the gaps matter more than the pitch.

The .pem is still a real secret. Broker moves the standing credential from the agent's environment to the App's private key a single, high value key that lives outside the repo and is git-ignored along with .env and audit.jsonl. That's a better key to have to protect, but it's still a key.

"Spend once" is a discipline, not an enforcement. Broker mints a token and uses it for exactly one call but the token it mints is a real GitHub installation token with a server-side expiry of roughly an hour. Broker does no local revocation, so within that window the token would technically still work if it leaked between mint and use. True oneshot, immediately-revoked credentials are future work.

And the policy engine is deliberately tiny: a single action against a single-repo allowlist. There's no per-caller policy, no rate limiting, no multi-tenant story yet. Those are extension points, not shipped features.

What's next

Two directions. First, other providers — the same pattern maps cleanly onto AWS STS (AssumeRole for short-lived, scoped credentials), and the provider layer is
where that plugs in. Second, the awkward reality that some services only offer long-lived keys: those can be wrapped behind the same policy-and-audit layer, so even a legacy secret is spent through a broker instead of handed to the agent.

The repo is open source and MIT-licensed:
github.com/Abhishekvoid/broker-mcp.
It's small enough to read in one sitting — kick the tires and tell me where it breaks.

A Successful Payment That Never Became a Booking: Building a Fault-Tolerant Payment Pipeline

Abhishek — Wed, 17 Jun 2026 08:25:41 +0000

A Successful Payment That Never Became a Booking

A customer completed their payment.

Razorpay showed Payment Successful.

The webhook returned HTTP 200.

The payment was captured.

And the booking sat there spinning on:

Still confirming...

Nothing had errored.

No exception.

No failed request.

No alert.

By every individual metric, the system was healthy.

Yet the one thing that mattered hadn't happened.

The customer had paid.

The creator had no booking.

This is the story of that bug, the investigation behind it, and the architecture we built so it can never happen again.

The lesson underneath all of it is deceptively simple:

Accepting money is easy. Guaranteeing that every successful payment becomes a confirmed booking is the actual problem.

What CreatorOS Is, and Why This Matters

CreatorOS is a booking and payments platform for independent creators, coaches, tutors, consultants, and freelancers.

A typical flow looks like this:

Client
   ↓
Select Slot
   ↓
Pay via UPI
   ↓
Booking Confirmed

Money moves through Razorpay.

Bookings live in our database.

When payments are part of the product, "mostly works" is not good enough.

A payment that vanishes into a stuck booking isn't just a bug.

It's:

A customer who paid and received nothing
A creator who appears unreliable
A loss of trust

And trust is the entire business.

The goal was never:

Process payments.

The real goal was:

Every captured payment must eventually become a confirmed booking.

The Naive Architecture (What Most Tutorials Teach)

Most payment tutorials teach something like this:

flowchart TD
    A[Razorpay]
    B[Webhook]
    C[Update Booking]

    A --> B
    B --> C

The webhook receives an event and immediately updates the booking.

Simple.

Clean.

Dangerous.

This architecture quietly carries every failure mode that matters:

Webhook retries
Duplicate deliveries
Partial failures
Race conditions
No recovery mechanism

The moment business logic lives inside a webhook handler, correctness becomes dependent on delivery success.

That is a fragile system.

Moving To Event Sourcing

The first major architectural decision was:

Webhooks should record events, not perform business logic.

Instead of updating bookings directly, we introduced an event ledger.

flowchart TD
    A[Razorpay Webhook]
    B[payment_events]
    C[Processor]
    D[Bookings]

    A --> B
    B --> C
    C --> D

Three tables became the foundation of the system:

Table	Purpose
payment_orders	Provider truth
payment_events	Immutable event ledger
bookings	Business truth

This design gives us:

Durability

Events are safely stored before processing.

Auditability

Every state transition can be traced.

Replayability

Reprocessing means replaying events.

Idempotency

Duplicate deliveries become harmless.

The webhook now has one responsibility:

Verify Signature
      ↓
Store Event
      ↓
Return 200

Nothing else.

Two State Machines, Kept Separate

One subtle but critical decision:

Payment state and booking state are not the same thing.

Treating them as identical creates hidden bugs.

Payment State Machine

This reflects provider truth.

stateDiagram-v2
    [*] --> Created
    Created --> Authorized
    Authorized --> Captured
    Authorized --> Failed
    Created --> Failed

Booking State Machine

This reflects business truth.

stateDiagram-v2
    [*] --> Pending

    Pending --> PaymentPending
    PaymentPending --> Confirmed
    PaymentPending --> Cancelled

A payment being captured is merely an input into a booking becoming confirmed.

They are related.

They are not identical.

Keeping them separate makes reconciliation possible.

The Incident

Then it happened.

A customer paid.

Razorpay showed success.

The webhook arrived.

The event existed in the database.

And the booking remained:

payment_pending

The first query told the story:

SELECT event_type, processed
FROM payment_events;

Output:

payment.captured    false
order.paid          false

The events existed.

They simply had not been processed.

Everything looked healthy:

Razorpay worked
Webhook worked
Database worked

Yet bookings did not.

The Investigation

We traced a single booking through the system.

Using its correlation ID we followed the trail across:

payment_events
payment_orders
bookings

Every row looked correct.

Except for one field:

processed = false

Repeated everywhere.

So we manually invoked the processor:

curl \
-H "Authorization: Bearer xxx" \
https://creator-os.vercel.app/api/cron/process-events

Response:

{
  "processed": 15
}

Immediately:

Events became processed
Orders became captured
Bookings became confirmed

The processor wasn't broken.

It worked perfectly.

The moment it ran.

Root Cause: The Scheduler That Didn't Exist

The investigation ultimately revealed something surprisingly simple.

Webhook
   ↓
Event Stored
   ↓
Processor Exists
   ↓
Never Runs

Nobody was invoking:

processPendingEvents()

The processor was healthy.

The webhook was healthy.

The database was healthy.

The scheduler was missing.

This is the hidden cost of event-driven architecture.

Decoupling ingestion from processing is the right design.

But it creates a new dependency:

Something must reliably trigger processing.

Without that trigger, events accumulate forever.

Building Recovery Mechanisms

Adding a cron job wasn't enough.

The goal was:

Even if a webhook fails, the system must eventually recover.

Scheduled Processing

A scheduler drives several independent jobs.

*/5 * * * *

process-events

Processes payment events.

reconcile

Queries provider truth and recovers missed webhooks.

integrity

Validates system invariants.

Idempotency Everywhere

Retries should never create incorrect state.

The processor claims work using:

SELECT *
FROM payment_events
WHERE processed = false
ORDER BY created_at
FOR UPDATE SKIP LOCKED;

This guarantees:

Multiple workers are safe
Retries are safe
Duplicate deliveries are safe

Whether one processor runs or one hundred, results remain correct.

Proving It With CI

A payment system you cannot test is a payment system you cannot trust.

We built CI that spins up a real Postgres instance.

flowchart TD

    A[GitHub Actions]
    B[Postgres Container]
    C[Test Suite]
    D[117 Passing Tests]

    A --> B
    B --> C
    C --> D

The tests verify:

Duplicate webhook deliveries
Event replay
Concurrent processors
Reconciliation recovery
Booking confirmation invariants

Not just the happy path.

The guarantees.

Final Production Architecture

The architecture follows a simple principle:

Webhooks record
Events persist
Processors transform
Reconciliation guarantees
Schedulers trigger
Idempotency protects

What It Taught Us

A Successful Payment Is Not The Same Thing As A Successful Booking

They are different facts.

The gap between them is where customers get hurt.

Webhooks Should Record Events, Not Perform Business Logic

Business logic belongs in processors.

Webhooks should be fast, durable, and boring.

Every Critical Workflow Needs A Recovery Path

If your system only works when every webhook arrives on time:

It doesn't actually work.

It just hasn't failed yet.

Schedulers Are Production Infrastructure

A queue that nobody drains is just a place where work waits forever.

The trigger is as important as the processor itself.

Reliability Is A Feature

Customers never notice reliability when it exists.

They immediately notice when it doesn't.

Closing Thoughts

The hardest part of payments isn't collecting money.

Stripe, Razorpay, PayPal, and countless providers already solved that problem.

The hard part is guaranteeing that successful payments eventually become business outcomes.

That means:

Durable events
Idempotent processing
Reconciliation
Recovery paths
Operational visibility

The day we stopped thinking about payments as API calls and started thinking about them as distributed systems was the day the architecture became reliable.

And that reliability is ultimately what customers pay for.