Development practice
Connector credentials: from long-term authorization to scoped execution
Separate long-term authorization from a task’s execution rights. An inventory query illustrates credential storage, server proxying, temporary issuance and revocation as an auditable authorization design.
Design example: centrally manage long-term authorization and grant limited task access; target capabilities determine proxying or direct access.
Architecture: responsibilities
Administrator · authorize
Connect via OAuth or token and define workspace and resource scope.
Connect account and retain authorization ↓
Connector management service
Encrypt long-lived credentials; expose only what controlled server calls need.
Choose controlled proxy or temporary issuance by target capability ↓
Path A · server proxy
A proxy checks request permissions and holds credentials server-side when calling the target.
Path B · temporary issuance
When supported, issue constrained credentials for direct tool access.
Call with target-recognized credentials; target checks rights ↓
Target system · final checks
Validate audience, expiry, resource and action; execute the business operation.
Retain grant IDs, operation IDs and outcomes, not secrets ↓
Authorization and usage audit
Correlate request, grant and result; log identifiers and summaries, never secrets.
Execution flow
- 01
Identify caller and scope
Derive tenant, workspace, user and run context from verified identity, not Agent-claimed store permissions.
- 02
Narrow this request’s rights
Intersect user rights, connector grant, resource scope and approved action; choose proxying or issuance.
- 03
Call or exchange
Keep credentials server-side for proxying; give controlled tools only necessary temporary credentials for direct access.
- 04
Verify results and end access
Read results and correlate operationId; deny new issuance after expiry, disconnect or invalid approval.
Key design decisions
Encryption, signing and authorization differ
Encryption protects stored credentials, signatures detect context tampering, and authorization governs allowed actions. Signing is not encryption: credential-bearing context needs protected transport and must stay out of logs and browsers. A short-lived context signature is not a third-party access token.
The target must recognize temporary credentials
Use the target’s STS, OAuth exchange or scoped signing facility. A self-issued JWT does not grant third-party access. Constrain audience, resource, action and expiry using that protocol; keep long-lived tokens out of prompts, artifacts and generic tool arguments. Skills describe procedure; servers enforce rights.
Distinguish new requests from issued grants
Disconnecting can block new calls or issuance, but issued offline tokens may remain valid until expiry. Immediate revocation requires target support, online validation or grant-version checks. Short lifetimes reduce exposure but do not replace revocation; rotation must verify old credentials become invalid.
Example: read one store’s inventory
An enterprise owns several stores, but a task needs just one. Authorization verifies the user’s access and issues a five-minute inventory-read credential. It cannot change prices or read other stores. Stop new issuance when the task ends; immediate invalidation of issued credentials depends on target revocation or online checks.
{
"subject": "run-demo",
"audience": "inventory-service",
"resource": "stores/store-demo/inventory",
"actions": ["read"],
"ttlSeconds": 300,
"grantVersion": 4,
"approvalRef": "approval-demo"
}Scope and limits
Use a server proxy when the target lacks scoped temporary grants, keeping long-lived secrets away from execution tools. For direct access, define issuance protocol, scope, lifetime and revocation. Verify approvals, revocation and rotation at the target, not just token acquisition.