SDK Reference

Axec ships TypeScript and Python SDKs for the same principal boundaries. Choose the workflow by who is acting, then select your language in the paired code tabs.

Install

TypeScript

pnpm add @axec/sdk

The package is ESM and requires Node.js 22.5 or newer for server-side use.

Python

pip install -e "sdk/python"

Use pip install -e "sdk/python[fastmcp]" when your Python application needs FastMCP integration.

What the SDK does for an agent

The SDK is not an abstraction over every Axec API. It is the small protocol boundary an agent needs to establish authority, discover or invoke admitted capabilities, and continue a governed action safely:

flowchart LR
  Task[Agent receives a task]
  Principal[Select User, Application, or Service Account]
  Token[Acquire an exact-Resource token]
  Invoke[Call an admitted tool or capability]
  Outcome[Handle immediate, pending, or denied outcome]
  Evidence[Retain safe correlation data]

  Task --> Principal --> Token --> Invoke --> Outcome --> Evidence

For public clients, the SDK handles OAuth Authorization Code with PKCE (RFC 7636), a Resource Indicator (RFC 8707), and discovery from Protected Resource Metadata (RFC 9728) and Authorization Server Metadata (RFC 8414). The SDK does not decide consent, policy, approval, or current authority; Axec evaluates those server-side.

Choose a workflow

Use case	Cross-language reference	Runtime boundary
Act for a signed-in User	Delegated User access	Browser authorization creates a User GrantBundle for one exact gateway Resource. Never embed a confidential client secret in browser code.
Run an autonomous workload	Autonomous gateway access	Server-side only. The Application can call its own gateway using eligible vaulted or no-auth Connector attachments; it cannot borrow User Connections.
Automate tenant management	Management automation	Server-side only. Short-lived tokens target the canonical management audience and carry explicit management permissions; they cannot invoke MCP or inherit User authority.

Gateway access tokens are audience-bound to one exact Resource. Operation scopes such as mcp:invoke, connector:proxy, and credential:exchange select a top-level operation but never widen the underlying Grant or Application attachment.

Execution and credential boundaries

Prefer mediated MCP or proxy execution when Axec should enforce authority, policy, approval, and Data Protection on every request. Axec injects the approved credential server-side and returns only the governed result.

Governed credential release is narrower but less mediated: an eligible confidential delegated client may receive one exact Connector’s bounded provider OAuth access token. Axec governs delivery, not later direct provider requests, and cannot retract a token already released before its provider expiry. Refresh tokens, static credentials, User-entered secrets, and vaulted credentials are never released.

Build an agent around an authority boundary

Treat an agent as an Application with a narrow execution path, not as a new kind of identity or a holder of upstream secrets:

1. Choose the principal first. Use delegated authorization for work performed for a signed-in User, ApplicationClient or GatewayClient for autonomous work on workspace-owned authority, and ManagementClient only for tenant administration.
2. Model each callable integration as a Connector capability, then attach it to the gateway. The attachment is the administrator ceiling; a User Grant can narrow it further.
3. Send agent tool calls through the mediated MCP or proxy client. Axec resolves the current credential only after live authority and governance checks pass, so the agent never needs a provider token.
4. Treat a pending ActionRequest as a workflow state, not a completed call. Poll it for status, then retry the identical authenticated operation only after approval.
5. Keep conversation state, tokens, and secret-bearing results in the component that owns them. Store a correlation ID or safe outcome metadata for observability, never credentials or unrestricted payloads.

This pattern keeps the agent loop simple: discover only admitted tools, call one capability, handle an immediate, pending, or denied result, and use Axec evidence to explain the outcome. The workflow pages show the concrete TypeScript and Python interfaces side by side.