API & MCP Access

API & MCP Access

Aptiwise lets you submit workflows from scripts, integrations, and AI assistants — using the same access rules that apply in the app. A personal API token (ffat_...) is the credential for both surfaces.

---

Step 1 — Generate a token

1. Open your Profile page (top-right menu → Profile).
2. Scroll to the API & MCP Access section.
3. Click New Token, give it a name (e.g. Claude Desktop or My Script), and click Create.
4. Copy the token — you can retrieve it again at any time from the same section.

Access control: A token grants no more access than your normal user account. Each workflow submission is checked against that workflow’s submission criteria, just like the UI.

---

Step 2a — Submit via REST API

Find the workflow UUID

The workflow UUID appears in the URL when you open a workflow in the admin panel. You can also list all workflows you are eligible to submit using your API token:

curl https://your-domain/services/v1/api-tokens/external/workflows \
  -H "Authorization: Bearer ffat_..."

Response:

[
  { "uuid": "abc123-...", "name": "Expense Report", "description": "Submit expense claims" },
  { "uuid": "def456-...", "name": "Leave Request", "description": null }
]

Submit a workflow

curl -X POST https://your-domain/services/v1/api-tokens/external/workflows/{workflow_uuid}/submit \
  -H "Authorization: Bearer ffat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "amount": 1500,
      "reason": "Team offsite catering",
      "expense_date": "2026-05-25"
    }
  }'

Response:

{
  "instance_uuid": "a1b2c3d4-...",
  "status": "in_progress",
  "workflow_name": "Expense Report"
}

The fields keys must match the field names defined in the workflow form. Required fields must be included or the submission will be rejected.

Error codes

Code	Meaning
401	Token missing, invalid, or revoked
403	Your employee profile doesn’t satisfy the workflow’s submission criteria
404	Workflow UUID not found or the workflow is inactive
422	Required form fields are missing — the error detail lists the field labels

---

List registered assets

Use GET /api-tokens/external/assets to retrieve assets you have view access to. This is useful for building iteration lists in scheduled workflows — for example, fetching all registered server baselines before spawning one drift-check workflow per server.

curl "https://your-domain/services/v1/api-tokens/external/assets" \
  -H "Authorization: Bearer ffat_..."

Filter by category or name prefix

# All DigitalOcean assets whose name starts with "DO-"
curl "https://your-domain/services/v1/api-tokens/external/assets?category=DigitalOcean&name_prefix=DO-" \
  -H "Authorization: Bearer ffat_..."

Query parameters:

Param	Type	Description
category	string	Exact match on the asset’s category (e.g. DigitalOcean, AWS)
name_prefix	string	SQL LIKE prefix match on the asset name (e.g. DO- matches DO-12345)

Response:

[
  {
    "uuid": "550e8400-...",
    "name": "DO-87654321",
    "category": "DigitalOcean",
    "updated_at": "2026-05-30T14:22:00Z"
  }
]

Note: properties is intentionally omitted from this response — it may contain SSH keys, API credentials, or other sensitive configuration. Workflows that need the full properties load them internally via an asset: data_to step (see Asset Registry & Data Steps).

Access rules

You only see assets where your company_roles intersect with the asset’s view_roles. If an asset has no view_roles configured it is visible to all authenticated token holders in the company.

---

Step 2b — Connect an AI assistant via MCP

The Model Context Protocol lets AI assistants like Claude Desktop, Cursor, or Windsurf discover and submit workflows on your behalf.

Get your MCP config snippet

In the API & MCP Access section of your Profile page, expand How to install on an AI platform. Select your token and copy the config snippet — it looks like this:

{
  "my-script": {
    "type": "streamable-http",
    "url": "https://your-domain/services/v1/mcp",
    "headers": {
      "Authorization": "Bearer ffat_..."
    }
  }
}

The JSON key (e.g. my-script) is derived from your token’s name and is how the AI assistant labels this server in its sidebar.

Claude Desktop setup

1. Open Claude Desktop → Settings → Developer → Edit Config.
2. Paste the snippet into the mcpServers object.
3. Restart Claude Desktop.

The assistant will now list all workflows you are eligible to submit as callable tools.

What the AI assistant can do

Once connected, the AI assistant sees one tool per workflow you have access to (e.g. submit_expense_report). It can:

• Ask you to describe what you need
• Fill in the form fields automatically
• Submit the workflow and return the instance ID

The profile page also shows the exact tool name and a sample prompt for each workflow — expand the setup guide and select the workflow from the dropdown to see them.

---

Revoking a token

To revoke a token, go to Profile → API & MCP Access and click the trash icon next to the token. Any API calls or AI assistant connections using that token will immediately fail with 401.