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

01

Administrator · authorize

Connect via OAuth or token and define workspace and resource scope.

Connect account and retain authorization ↓

02

Connector management service

Encrypt long-lived credentials; expose only what controlled server calls need.

Choose controlled proxy or temporary issuance by target capability ↓

03

Path A · server proxy

A proxy checks request permissions and holds credentials server-side when calling the target.

04

Path B · temporary issuance

When supported, issue constrained credentials for direct tool access.

Call with target-recognized credentials; target checks rights ↓

05

Target system · final checks

Validate audience, expiry, resource and action; execute the business operation.

Retain grant IDs, operation IDs and outcomes, not secrets ↓

06

Authorization and usage audit

Correlate request, grant and result; log identifiers and summaries, never secrets.

Execution flow

  1. 01

    Identify caller and scope

    Derive tenant, workspace, user and run context from verified identity, not Agent-claimed store permissions.

  2. 02

    Narrow this request’s rights

    Intersect user rights, connector grant, resource scope and approved action; choose proxying or issuance.

  3. 03

    Call or exchange

    Keep credentials server-side for proxying; give controlled tools only necessary temporary credentials for direct access.

  4. 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"
}
Illustrative data contract, not a callable API.

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.

Continue reading