Context

Modern computing architectures use multiple independently running workloads that are often invoked in order to process external API calls. These workloads run in isolated networks that can be compromised by attackers, leading to unauthorized actions such as: invocations without explicit transaction context, arbitrary client identity impersonation, parameter modification and theft of OAuth access tokens.

Transaction Tokens

Transaction Tokens (txn-tokens) are short-lived JWTs (JSON Web Token) designed to preserve caller identity, workload identity, and authorization context throughout a “Call Chain” within a Trust Domain. They are meant to prevent unauthorized invocations, parameter tampering, and token theft in multi-service architectures, problems anyone running microservices has encountered.

Scenario

Following diagram describes a scenario where txn-token is used to preserve caller identity and authorization context for a call on an external API endpoint deployed on an API Gateway.

Terms Used

Following terms are used in this post. They are listed verbatim from the spec.

Call Chain: The set of invocations across all workloads invoked to complete the requested transaction.

Trust Domain: A logical grouping of systems that share a common set of security controls and policies. In practice this may include a virtually or physically separated network, which contains two or more workloads. The workloads within a Trust Domain may be invoked only through published interfaces.

External Endpoint: A published interface to a Trust Domain that results in the invocation of a workload within the Trust Domain.

Transaction Token (Txn-Token): A signed JWT with a short lifetime, providing immutable information about the caller or workload, certain parameters of the call, and specific contextual attributes of the call. The Txn-Token is used to authorize subsequent calls in the Call Chain.

Transaction Token Service (TTS): A special service within the Trust Domain that issues Txn-Tokens to requesting workloads. Each Trust Domain using Txn-Tokens MUST have exactly one logical TTS.

Objectives

The authors of the spec are trying to achieve the following objectives.

Scope Narrowing

The spec mandates that Txn-Tokens scope should be “as narrowly defined as possible” and that the Transaction Token Service must ensure requested scope is equal to or less than the subject token’s scope. An example of a broad scope is api:delete that applies to delete action on any resource of the API while a scope such as account:delete only applies to the delete operation on the “account” resource of the API.

Short Token Lifetimes

Txn-Tokens are expected to be short-lived (on the order of minutes or less). A narrowly scoped, short-lived, transaction token reduces the attack surface of captured and replayed transaction tokens.

Transaction Traceability

The txn claim provides transaction traceability across the entire call chain. This will be invaluable for distributed tracing, debugging and root cause analysis.

Separation of Request and Transaction Contexts

The spec distinguishes between environmental context (IP address, auth method, etc.) and authorization details (parameters, computed values) using request context (rctx) and transaction context (tctx). This separation is good.

Scope Narrowing Requires Business Logic

In this post, I want to discuss issues behind scope narrowing, when performed by TTS.

The spec says the TTS “MUST ensure that the requested scope of the Txn-Token is equal or less than the scope(s) identified in the subject_token” (Section 14.6). It also says that scope should be “as narrowly defined as possible” for the transaction’s purpose. More specifically, “The values used for this claim are defined by the TTS as representative of the authorization model defined by the Trust Domain. The value may be literately and semantically different from, and represent an intent narrower, than a scope value issued to an external client.”

Question is how does the TTS know what scope is appropriate for a given business transaction?

Consider the following example.

External Request: scope=transfer:write (OAuth token)
Internal Transaction(s): "application wants to transfer USD 1,000,000.00 from one account to the other account after checking validity (good standing) of both the accounts, check transaction limits for each accounts according to their respective business policies"
Appropriate Txn-Token scope: ???

The TTS would need to maintain a mapping table like the following.

external_scope: transfer:create
transaction_type: check account standing
→ txn_scope: account:read

external_scope: transfer:create
transaction_type: check account limits
→ txn_scope: limits:read

external_scope: transfer:create  
transaction_type: check business policies for accounts
→ txn_scope: business-policies:read

external_scope: transfer:create  
transaction_type: transfer funds
→ txn_scope: transfer:create

external_scope: transfer:create  
transaction_type: account credit
→ txn_scope: account:update

external_scope: transfer:create  
transaction_type: account debit
→ txn_scope: account:update

This is business logic. The TTS now needs to understand application’s authorization model, which services need which permissions, and how to derive narrow scopes from broad external scope. This violates separation of concerns principle of design considering that TTS should be infrastructure, not an application-aware policy engine.

Architectural Choices

Here are possible architectural choices.

Option A: TTS with business logic

• TTS maintains a scope derivation policy engine
• Pros: Centralized scope management, guaranteed narrowing
• Cons: TTS becomes application-aware, harder to operate, doesn’t scale across different applications in the same trust domain

Option B: Caller-driven narrowing

• Services request specific scopes, TTS only validates a subset of relationship
• Pros: TTS stays generic infrastructure, scales across apps
• Cons: Requires all services to understand scope narrowing, easier to get wrong

Option C: Hybrid

• Edge services translate external OAuth scopes to internal transaction types
• Pros: TTS has a simple mapping: transaction_type → internal_scopes
• Cons: Internal services validate scopes as needed

The spec currently implies Option A without acknowledging the operational complexity. Most implementations will probably do Option B and call it good enough considering the complexities of business transactions performed by APIs.

What We Did

We punted on scope narrowing in our solution. Since Tx-Tokens spec was not in public domain, we used a service that implemented RFC 8693 Token Exchange to mint our JWTs with some proprietary claims. Our TTS did a simple scope passthrough:

• If subject_token has scope transfer:read,transfer:create, the Txn-Token gets the same scope
• Upstream services are responsible for checking if the token’s scope includes what they need
• We relied on service-level authorization: “I need orders:read, does this token have it?”

Here Is My Take

TTS should stay as a generic infrastructure to scale across business applications of modern enterprises.

API Gateway being an infrastructure service should not deal with any non-trivial business logic, esp. when required transaction context (such as amount, limits, etc.) resides in payload. This pushes the business logic back to each service (first internal service, etc.), which has the context to know “this is a check account standing operation, it only needs account:read.”

It is understandable that the authors of the specs would not want to bloat the spec by addressing all possible design choices for TTS for the narrow scoping requirement. However, that also questions the usability of addressing the same requirement. Should it even be in the scope for the spec?

Summary

The Transaction Tokens spec is at draft-08, so it’s maturing. The core concepts such as short-lived, preservation of authorization context and immutable context tokens solve real problems.

The challenge is bridging the gap between “this should work in theory” and “this works in our production environment with 200 services, 5 datacenters, and routine network partitions.” The spec has good bones, but needs more operational battle scars to become truly production-ready.

I have a couple of other issues that I will try to discuss in subsequent posts.

Have you implemented OAuth token propagation in microservices? What problems did you hit that specs don’t cover? I’m particularly curious about TTS deployment patterns people have tried.

One CLI for all of Google Workspace — built for humans and AI agents

gws doesn’t ship a static list of commands, instead it reads Google’s own API Discovery Service at runtime and builds its entire command surface dynamically. When Google Workspace adds an API endpoint or method, gws picks it up automatically.

We want to talk about that API Discovery Service in this post.

Google API Discovery Service

Google first presented the Google API Discovery Service way back in Google I/O 2011! They described it as a service that exposes metadata about Google APIs in a machine-readable format called “Discovery Document” for client libraries and other tools to consume.

Google Discovery Document (GDD)

Google Discovery Document is a machine-readable document for each Google API. Each document contains a list of API methods and available parameters for each method, a list of available OAuth 2.0 scopes, and inline documentation of methods, parameters, and available parameter values.

API definition/ description

At the time Google was working on the API Discovery Service, OpenAPI was not born yet and Swagger ¹ was not as ubiquitous and popular. Fast forward now, there are more popular API definition/ description languages available. Depending on the maturity of the organization, one may find APIs defined using one of these: OpenAPI specification (OAS), AsyncAPI specification, Web Services Description Language (WSDL), JSON RPC, Google Discovery Document, Protocol Buffers, etc.

A modern API Discovery Service would need to support APIs defined using one or more such languages.

Consuming APIs

To understand the importance of the API Discovery Service, let’s first understand how APIs have been consumed and would be consumed.

Developer Portal

Typically, API producers would make API documentation available on a Developer Portal. Content on developer portal is organized for human developers building business process integrations. Modern developer portals generate API references automatically from machine-readable API definitions. Developer portal is also used for documenting APIs that do not have machine-readable API definitions.

Developing integrations conventionally

Application developers would read API related content from the developer portal, use provided SDK (like gws) or download API definition if available and generate client-side code from the definition using tools available and code the integration in their applications.

Developing integrations using AI code assistants

Cisco recently released an MCP (Model Context Protocol) server for its DevNet (developer portal) content. This MCP server enables IDE AI assistants (Github Co-pilot, Cursor, Claude Code, JetBrains AI, etc.) to call tools searching Cisco’s API documentation. This enables software developers to have more accurate, official and most current context regarding Cisco APIs without switching windows.

Cisco advises that output from any AI assistant using their MCP server can be incomplete, incorrect, or insecure and advises to treat the generated code the way you would, a draft from a junior colleague: review it, test it, and approve it before running it in any real environment.

Integrations with Agentic AI

Agentic AI refers to AI systems that don’t just respond to a single prompt, but autonomously pursue goals across multiple steps — planning, taking actions, observing results, and adapting until the task is complete. Here, the system decides what to do next rather than waiting for a human to direct every step.

Most agentic systems run a continuous cycle:

Think → Act → Observe → Think → Act → …

This is sometimes called a ReAct loop (Reasoning + Acting). The agent reasons about what to do, does it, sees what happened, and reasons again — until the goal is met or it gives up.

Here is an example of an agentic behavior — notice no human directed API calls.

• The agent (Claude/OpenClaw) receives a goal — “investigate alert abc-123”
• It selects the right skill or MCP tool
• Executes a sequence of API calls either directly using skills with CLI, script or indirectly using MCP tools wrapping one or more APIs
• Observes each response and passes outputs into the next step
• Produces a final synthesized report

Multiple approaches for calling an API

• The agent decides at runtime whether to load a skill or call an MCP tool
• A skill is lazy-loaded markdown — the agent reads it and directly executes what it describes (CLI commands or scripts)
• An MCP tool is a function the agent calls via the MCP protocol — the MCP server handles actual execution
• Both paths ultimately reach the external API, but via different execution models — local shell vs remote process

Agentic AI Workflows Using Google Workspace APIs

Now that we know how agentic AI workflows work, following diagram shows how an agent would use gws CLI or MCP tools to call Google Workspace APIs with the help of Google’s API Discovery Service.

• Path A — CLI: agent runs gws gmail +triage directly as a shell command — no MCP server needed, agent’s native terminal access is enough
• Path B — MCP: agent calls gws mcp as a stdio MCP server, exposing all Workspace tools via the MCP protocol for the agent

Each process fetches the Google Workspace API schemas independently from the Google API Discovery Service when it starts up, before handling any requests. For both paths, gws queries at startup to build its command surface dynamically — so new Workspace API endpoints appear automatically without any CLI update.

Are you ready for Agentic AI?

Isn’t it wonderful to know that Google can still use its API Discovery Service that was designed and developed fifteen years ago for a new CLI (gws) that is built for humans and AI agents? It keeps giving them good return on investment. Kudos to them!

If you have invested in exposing your business capabilities as APIs while digitally transforming your organization, you have already formed a backbone for Agentic AI driven business processes. Making your APIs easily discoverable to rapidly evolving agentic AI ecosystem of agents, frameworks, platforms, etc. is only going to increase return on your investment in APIs.

Question to CIOs and their leadership teams

Do you have something like Google’s API Discovery Service in-house?

If the answer is no or you want to know more about channelseal, let’s talk.

Let’s talk

As an industry-standard, OpenTelemetry is supported by more than 90 observability vendors, integrated by many libraries, services, and apps, and adopted by numerous end users. Head to OpenTelemetry->ChannelSeal integration to know more about how seamlessly you can send 3rd party API traffic metadata to ChannelSeal using the OpenTelemetry observability protocol and framework.

That’s the problem we started channelseal to solve.

Why We Started This Blog

We’ve spent years working at the intersection of APIs, security, and data governance. In that time, we’ve seen the same story play out over and over: a company builds out a robust internal security posture, only to discover that sensitive company data has been quietly flowing through a forgotten, unknown or know third-party integration for months. Not because anyone was careless — but because the tools to see it simply didn’t exist.

Third-party APIs have become one of the largest and least understood attack surfaces in modern software. Non-human identities (NHI) — API keys, service tokens, OAuth credentials — now outnumber human users in most organizations. Shadow integrations accumulate faster than they can be tracked. And as AI agents and plugins enter the picture, the complexity is only growing.

channelseal blog is our attempt to cut through that complexity.

The Agentic AI Inflection Point

If third-party integrations were already hard to manage, agentic AI has turned the dial up dramatically.

Until recently, API calls were initiated by humans or by deterministic code a developer had written and reviewed. Today (or soon), AI agents would autonomously decide which tools to call, which data to retrieve, and which external services to interact with — often in real time, often without a human in the loop. A single AI agent orchestrating a business workflow might touch a dozen third-party APIs in a single session: pulling data from one, writing to another, triggering actions in a third.

This creates a new class of risk that most security teams aren’t yet equipped to handle.

What You Can Expect Here

We’ll be writing about the realities of third-party API security: the risks organizations don’t realize they’re taking, the patterns we see across the industry, and the practical steps teams can take to get visibility and control over their integration landscape. We’ll share technical deep-dives, lessons from the field, and honest takes on where the industry is headed.

We’re not here to sell fear. We’re here to share what we know — and to help security, engineering, and product teams build integrations they can actually trust.

Let’s Get Started

channelseal is built on three ideas: Discover what’s connecting to your systems, Monitor how data moves through those connections, and Protect what matters most. Everything we write here will connect back to those principles in one way or another.

Thanks for being here at the beginning. We’re just getting started.

— The channelseal Team

Have a topic you’d like us to cover? Reach out at hello at channelseal dot com.