Service Accounts

A Service Account is a non-human identity for automating Axec Account management. It belongs to exactly one Account.

Use a Service Account to create and manage resources programmatically, such as Applications, Connectors, Dependencies, Connections, and other Service Accounts. It cannot invoke MCP tools or act for a User.

Example: A deployment pipeline uses a Service Account to create a new Application and attach a Connector whenever the team releases a new integration.

A Service Account is different in purpose from an Application Credential. An Application Credential lets agents call or expose governed runtime capabilities. A Service Account manages Account resources instead.

A Service Account authenticates with an Account-issued client ID and a long-lived secret. It presents them at the Account token endpoint, and Axec issues a short-lived management token in return. Keep the secret server-side and send it only to the token endpoint. The token works only for the management API.

Permissions

Each Service Account has a permission ceiling: the maximum management permissions it can request. An Account administrator assigns the ceiling when creating the Service Account.

The client requests only the scopes its current operation needs. Axec checks them against the ceiling:

• A request within the ceiling returns the expanded permission set.
• Axec rejects a request that exceeds the ceiling. It does not silently issue a narrower token.

Some permissions imply a read permission on the same resource. For example, applications:write also grants applications:read.

Common permissions:

Permission	Allows
applications:read / applications:write	View or create Applications
connectors:read / connectors:write	View or provision Connectors
serviceaccount:read / serviceaccount:write	View or manage Service Accounts
security_events:read / security_events:export	View or export security events
activity:read	View Account activity

Axec also provides reviewed presets:

• Connector manager: connectors:write
• Application manager: applications:write, connectors:read
• Integration provisioner: applications:write, connectors:write
• Audit reader: activity:read, security_events:read, risk:read
• Audit exporter: the Audit reader permissions plus security_events:export

Assign the smallest set that completes the task.

Create and manage resources

The management API creates and changes Account resources.

Example: Create an Application with one Connector dependency:

import { ManagementClient } from "@axec/sdk/management";

const management = new ManagementClient({
  baseUrl: "https://axec.dev",
  account: "acme",
  clientId: process.env.AXEC_SERVICE_ACCOUNT_ID!,
  clientSecret: process.env.AXEC_SERVICE_ACCOUNT_SECRET!,
});

const created = await management.workspaceApi().createApplication({
  display_name: "Support Assistant",
  client: {
    client_key: "server",
    type: "confidential",
    redirect_uris: ["https://assistant.example.com/oauth/callback"],
    offline_enabled: false,
  },
  dependencies: [
    {
      connector_key: "jira",
      ceiling_revision: 3,
      allowed_capability_keys: ["issues.read"],
    },
  ],
  idempotency_key: "setup-018f2e7c",
});

This operation requires applications:write, and connectors:read when it selects Connectors.

Credential lifecycle

Each credential generation has its own identity and lifecycle. Axec returns the plaintext secret once and stores only a hash.

To rotate, issue a replacement, deploy it, then revoke the old generation. Multiple generations can remain active during the change.

Continue

• Automate management with a Service Account
• Management automation SDK