Did you know? A token can be active but still lack permission for your request. Correct AI integrations must check the issuer’s metadata and the intended resource before acting.
Quick answer: ask the authorized issuer for current state, verify active, scope and audience, enforce resource ownership, use safe cache rules and obtain a separate receipt for the final operation.
This chapter continues How Super Intelligence Works. Every school example is a fictional teaching case.
Contents and reading routes
- 1. Quick answer: active is not a universal permission
- 2. What problem introspection solves
- 3. The RFC 7662 endpoint
- 4. The active boolean is required
- 5. Why active can still be insufficient
- 6. Scope is a set of delegated capabilities
- 7. Audience binds a token to its intended destination
- 8. Client and subject identities are separate
- 9. Expiration is not the entire revocation story
- 10. An authorized introspection response is sensitive
- 11. Active false is not always an account-closure claim
- 12. Introspection endpoint failures need their own category
- 13. A fictional ledger of 75 delegated requests
- 14. Caching introspection results is a policy choice
- 15. Do not confuse cache freshness with authorization
- 16. How JWT validation relates to introspection
- 17. Why the token endpoint is not the introspection endpoint
- 18. An API request is not complete when introspection passes
- 19. A practical verification sequence
- 20. A changed-context exercise: parent consultation notes
- 21. Negative tests that protect real users
- 22. Six questions and checked answers
- 23. Frequently asked questions
- 24. Official sources and related reading
1. Quick answer: active is not a universal permission
Did you know? An API token can be active and still be entirely wrong for the action an AI assistant wants to perform. Active usually means a provider recognizes the token as currently valid under its rules. It does not automatically mean that the token belongs to the correct parent, allows access to this student’s record, authorizes publication, or can be presented to every resource server.
OAuth token introspection lets an authorized resource server ask an authorization server about a token it received. RFC 7662 defines an introspection endpoint and metadata such as active status, scope and other contextual claims. A careful agent integration uses that verified metadata as one ingredient in its resource-specific authorization decision. It never treats ‘active=true’ as permission to do anything.
2. What problem introspection solves
In OAuth, a client can receive an access token after the resource owner grants an appropriate authorization. The protected API needs to determine whether that token is acceptable when a request arrives. Some tokens are structured so they can be validated locally, while others are opaque identifiers whose interpretation belongs to the issuer. Introspection provides a documented protocol for getting relevant state from an authorization server.
The client holding the token does not ordinarily need to understand its internal form. The resource server asks the issuer or its authorized introspection service for metadata needed to enforce a policy. That division prevents an AI assistant from inventing a token’s permissions based on how long it looks or what text appears in its characters.
3. The RFC 7662 endpoint
RFC 7662 defines an endpoint that takes a token and returns a JSON introspection response. The endpoint itself needs appropriate TLS protection and caller authorization. It is not a public dictionary service through which anyone can probe whether another person’s credential exists or inspect their account information.
The resource server must use the issuer’s documented endpoint and authentication requirements. It should not send a bearer token to a URL supplied in arbitrary tool output or a webpage. Token values are secrets. They should be transmitted only through the intended protected channel, not embedded in public logs or an unreviewed query string.
4. The active boolean is required
The introspection response has a required active member. A properly authorized query for an inactive, invalid or undisclosable token normally returns active:false under RFC 7662 rather than being treated as a server error. By contrast, a caller that lacks permission to introspect may receive an HTTP authorization error. Those states mean different things.
An agent should report ‘token inactive’ only when it has an authoritative response establishing that status. If the network times out or the resource server cannot authenticate to the introspection endpoint, the token’s current status may be unknown. In that situation, a high-risk operation should not be permitted on the assumption that the introspection call probably would have succeeded.
5. Why active can still be insufficient
Consider a fictional family portal with two API tools: read lesson schedules and publish private progress notes. A token might be active for schedule.read but not have notes.write. If the AI assistant invokes the publishing tool merely because active is true, it has skipped the permission that protects an important action.
The server should check the granted scope, permitted audience and current user’s resource relationship as required by the application. Even a valid notes.write scope may not authorize editing a note about a student outside the family. The scope expresses one permission layer, while the target record’s ownership and local policy provide others.
6. Scope is a set of delegated capabilities
Introspection may return scope as a space-separated string of values. The values are defined by the authorization system’s actual contract. An assistant should not guess that two similar-looking scope names have the same meaning. A read scope does not imply a write scope, and a connection approved for one tool may not be reusable for a different provider.
For example, a token granted calendar.read can be sufficient to summarize a selected lesson calendar. It should not be silently repurposed to delete an event or export unrelated contact information. When a user needs an additional capability, ask through the provider’s legitimate authorization workflow instead of using a different endpoint that happens to accept the same token.
7. Audience binds a token to its intended destination
An introspection response may include aud, indicating an intended audience. A resource server must evaluate audience according to the relevant token and provider policy. A valid access token meant for a calendar API is not automatically acceptable to a student finance endpoint even if both belong to the same organization.
Audience checks defend against a confused service accepting tokens from the wrong context. An agent should not present one token to arbitrary APIs and choose whichever service returns HTTP 200. Use the right protected resource and validate that the token’s intended recipients match the request being authorized.
8. Client and subject identities are separate
Relevant metadata can identify the OAuth client associated with a token and its subject or other authorization context. The software client making the request is not necessarily the human resource owner. Two parents may connect the same third-party calendar application, yet their delegated tokens and authorized data must remain separate.
Bind the introspected authorization to the actual account and resource relation in the application. A display name is not a stable account key. Do not let an AI model merge two people because both are called ‘Mrs Tan’ or because one public school website displays the same address. Use verified identities and scoped resource IDs.
9. Expiration is not the entire revocation story
A token can be issued with an expiration time, but the issuer may revoke it earlier if the user disconnects an integration or an administrator withdraws authority. A locally cached exp claim cannot by itself establish that the token has not been revoked. Introspection offers one way to consult more current issuer state when that provider supports it.
However, introspection is not an unlimited promise of immediacy. Provider processing, caching and network conditions affect what the resource server knows at an instant. A safe service sets freshness rules appropriate to the action’s consequences. A sensitive write may require more current evidence than displaying a recently cached public schedule.
10. An authorized introspection response is sensitive
Introspection can expose user identifiers, scopes and metadata about authentication. The RFC includes privacy considerations because this information could reveal details to an unintended caller. The server should disclose only what the requesting resource server is entitled to learn and should protect the endpoint with suitable client authentication and encrypted transport.
Logs should normally store an opaque operation ID, issuer identity, status classification and minimal decision metadata rather than the raw bearer token or full personal profile. A model that asks for the full token to ‘check whether it looks correct’ is weakening the system. Use the real introspection service, not chat-based token inspection.
11. Active false is not always an account-closure claim
RFC 7662 permits an authorization server to return active:false where a caller is not authorized to know about the token. Therefore the same result may mean expired, revoked, unknown or not disclosable to this resource server. An AI assistant should not infer that the parent’s account has been terminated from that one response.
The safe user-facing message is narrower: ‘This connection cannot currently authorize the requested action.’ If appropriate, direct the user to reconnect through the official provider or contact support. Avoid speculation about security incidents when the provider intentionally hides detailed validity information.
12. Introspection endpoint failures need their own category
A transport timeout, TLS validation error, HTTP 401 from the introspection service and a successful JSON response containing active:false are distinct outcomes. Conflating them can lead to unnecessary reconnect prompts or, worse, letting a protected action proceed without proof.
A reliable service records whether the verification call itself was authorized, whether the response was well-formed, whether the token was active and whether the requested scope and audience passed. Do not retry indefinitely on permanent configuration errors. Bound transient retries, respect business deadlines and keep uncertain high-stakes actions uncommitted.
13. A fictional ledger of 75 delegated requests
Imagine seventy-five requests for an invented parent learning portal. Forty-six have current verified active tokens and pass all requested scope, audience and resource checks. Nine are inactive according to authorized introspection; seven are active but lack the necessary scope; five have an unacceptable audience; four fail resource ownership checks; and four have unresolved verification-service outcomes. The total is 46 + 9 + 7 + 5 + 4 + 4 = 75.
Only forty-six should be counted as authorized for their requested operations, about 61.33 percent. An ‘active token’ success metric would miss the scope, audience and ownership failures. The counts are fictional classroom examples, not production measurements. A transparent report separates denied access, unknown verification and completed business effects instead of announcing seventy-five successful tool calls.
14. Caching introspection results is a policy choice
Checking every token against an authorization server on every request may increase network cost and latency. Some providers and resource servers cache introspection results for a defined period. But a cached active result can remain in memory after a user revokes access, creating a time window in which the application has stale evidence.
Choose a cache lifetime and invalidation design according to token expiration, revocation requirements and the sensitivity of the operation. Keep cache keys scoped to the issuer, token and relevant caller context. If one resource server is allowed to see a different subset of metadata than another, sharing an unscoped cached response can reveal information or grant incorrect permissions.
15. Do not confuse cache freshness with authorization
A locally retained introspection response may be fresh enough for a low-risk read while being too old for a consequential export or publication. Even when the cache is current, the resource-specific ownership relationship may have changed in the application database. The checks protect different facts.
For instance, a parent might remain signed into the same portal while a school administrator removes the parent’s access to a particular student record. The active token may continue to identify the parent, but the record-level permission must be recalculated or checked at the appropriate trusted authority. Do not rely solely on an identity token to decide which family information can be shown.
16. How JWT validation relates to introspection
A signed JWT may contain claims that a resource server can validate locally using trusted keys and issuer rules. Introspection can provide additional state for deployments that support it, including revocation context. Neither approach is universally required for all OAuth systems, and a JSON-looking token should not be treated as self-validating.
A locally validated signature does not make the claims current forever; a successful introspection response does not remove the need to check scope and target resource. The choice depends on issuer configuration and threat model. For key-validation details, a separate chapter covers JWKS rotation and why the token’s declared algorithm must not control trust by itself.
17. Why the token endpoint is not the introspection endpoint
The token endpoint issues or exchanges credentials under the provider’s OAuth protocol. The introspection endpoint reports state and metadata to authorized resource servers. Calling the wrong endpoint can yield confusing errors or expose secrets to components that were not meant to receive them.
An agent developer should obtain both endpoint URLs from the issuer’s trusted configuration or documented discovery, not guess one by changing path segments. Authentication to introspection may differ from authentication for token issuance. A working end-user OAuth connection does not automatically grant the app permission to query every token’s metadata.
18. An API request is not complete when introspection passes
An active token with appropriate scope authorizes consideration of an operation, but the application still has to execute it and verify the result. A tool can fail after authorization because of a stale record version, provider outage or validation error. The assistant should not claim that an email was sent just because the token was accepted.
Preserve operation IDs and destination receipts. If a write times out, read the authoritative target state before replaying it. This is particularly important for publishing posts or sending communications where duplicate side effects are visible to users. Authentication state and business completion need separate labels in the agent’s ledger.
19. A practical verification sequence
On receiving a request, determine the correct resource server, issuer and requested operation. Authenticate the calling agent to its local service, obtain the delegated token through the approved storage mechanism, and ask the intended issuer for introspection when required by policy. Validate the server response and the current active state.
Next verify granted scopes, permitted audience, client identity and the current user’s relationship to the target. Apply local limits and explicit approval for consequential writes. Only then perform the requested action, using stable operation identity, and collect a verifiable destination receipt. Log denial categories without leaking the token.
20. A changed-context exercise: parent consultation notes
A fictional tutor asks an authorized assistant to retrieve three consultation notes for the families attending a small group. The token is active and grants notes.read, but the tutor’s service role currently permits only two of those three families. Correct behavior is to retrieve the two authorized notes and refuse the third, with a clear explanation of the denied scope.
Now suppose the token issuer becomes unreachable while the agent is processing a fourth note. The system should follow its defined verification-freshness policy, not manufacture an active response because similar notes were previously accessible. If proof is insufficient for a private record, hold the action and surface the need to reconnect or retry after verification is restored.
21. Negative tests that protect real users
Test a truly inactive token, an expired token, a revoked token, an audience mismatch, insufficient scopes, a malformed response and an introspection caller with no permission to use the endpoint. Verify that denied requests cannot leak whether another person’s token exists or reveal private subject metadata.
Test a cached active response after revocation and a cache entry from a different issuer. Test resource-level permission changes even when the same token stays active. Finally simulate a crash after an authorized external write to ensure the agent does not duplicate the effect on restart. Each test targets a different trust boundary.
22. Six questions and checked answers
Question one: does active:true automatically authorize any tool? No. Question two: does active:false always prove an account was closed? No. Question three: can a token have the correct signature but the wrong audience? Yes. Question four: should an authorization server disclose full token metadata to any anonymous caller? No.
Question five: can a cached active result outlive a real revocation event? Depending on design, yes. Question six: does accepted token status prove a public post was published? No. A rigorous agent separates token state, permission decision and external completion.
23. Frequently asked questions
What is OAuth token introspection? A protocol for authorized protected resources to query a token’s current state and metadata. What is the active field? A required boolean in an RFC 7662 response. Does active mean write permission? No, scope and resource policy still apply.
Does introspection require TLS? The standard requires transport protection. Can the client show a raw token in chat? It should not. Can introspection be cached? Depending on the deployment, with freshness and revocation trade-offs. Does this article claim ASI exists? No; it teaches existing API security patterns.
24. Official sources and related reading
Start with RFC 7662: OAuth 2.0 Token Introspection for the endpoint, active field, metadata and privacy rules. For token fundamentals, use RFC 6750: Bearer Token Usage and current issuer documentation. The implementation must follow its actual authorization server’s endpoint and scope semantics.
Continue within eduKateSG with OAuth PKCE, Agent Secret Rotation and Policy-as-Code. The full series is How Super Intelligence Works. A legitimate agent uses introspection to narrow authority, never to assume more of it.