Skip to content

Integrations

Asana SDK: get started

The complete Asana API through typed application or agent clients

Use an ordinary App, or an Agent when the workload needs agent identity. Alter builds provider requests from a reviewed contract and applies the same connection authorization, policy, approvals, and audit records as raw requests.

Terminal window
npm install @alter-ai/sdk @alter-ai/asana
# Python (installs core automatically)
pip install alter-sdk-asana

The provider package includes only Asana types and response schemas and pins its contract version.

Configure Asana with Full permissions (default) and retain each customer’s grant ID after Connect consent. Existing OAuth connections keep this scope mode; granular OAuth scopes are not offered. Alter supplies the credential; it never belongs in operation input.

import { App } from "@alter-ai/sdk";
import { AsanaIntegration } from "@alter-ai/asana";
const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
const client = new AsanaIntegration(app, { grantId: process.env.ASANA_GRANT_ID! });
const result = await (await client.workspaces.getWorkspaces({})).wait();
console.log(result.bodyJson());
} finally {
await app.close();
}
from alter_sdk import App
from alter_sdk_asana import AsanaIntegration
async def first_call(api_key: str, grant_id: str):
async with App(api_key=api_key) as app:
client = AsanaIntegration(app, {"grant_id": grant_id})
call = await client.workspaces.get_workspaces({})
result = await call.wait()
return result.body_json()

Contract 2026-11-06 publishes 245 reviewed operations. The complete policy inventory covers 278 operations from Asana’s official core/SDK exports and issuer metadata; 33 protocol or security-capable operations are cataloged with explicit SDK exclusions. The API reference links every operation to its complete input fields, response models, TypeScript and Python examples, and policy identity. Browse by resource under this provider’s API reference in the Integrations sidebar, or download the pinned OpenAPI specification. The Developer Portal provider view and alter integrations operations asana --version 2026-11-06 also expose the schemas.

Generated calls pin the Alter contract version. Asana’s own product, role, scope and subscription requirements still apply. There is no silent version fallback and no automatic write retry or pagination.

Terminal window
alter integrations execute asana asana.getworkspaces \
--version 2026-11-06 --grant "$ASANA_GRANT_ID" --input '{}' --wait

Arguments use native path, query, headers, and body containers. Array query parameters are sent the way the provider’s document declares them: one delimited value where it declares explode: false (or a pipe- or space-delimited style), repeated keys otherwise. SDK methods preserve provider field names, decimal lexemes and large integers as strings when necessary. HTTP 204 returns null / None from the typed decoder. Binary responses use bodyBytes() / body_bytes(); the CLI can save them with --output-file.

A policy rule can require approval for any operation. The call returns a pending approval; wait() resolves once the approver decides, and resume(approvalId) picks a pending approval up after a restart. Approval cards show the operation, its contract version and the request input the sensitivity review marked safe to display.

attachments.createAttachmentForObject / attachments.create_attachment_for_object uploads named multipart parts. Supply the file as an object with filename, content_type and content_base64; other fields retain their provider names. The serialized managed input is limited to 5 MiB. File content is held encrypted for approval and masked; the upload manifest shows its name, media type, length and digest.

Use OAuth, an Asana personal access token (asana managed-secret template), or a service-account token (asana-service-account). Save tokens through managed-secret authoring and grant the saved connection to the application; never put them in SDK arguments. Service-account tokens must have Full Permissions for standard endpoints and the additional Asana authorization required for restricted features. The seven service-account-only operations cover AI Studio runs and seats, audit logs, workspace events, resource exports, and creating or reading organization exports. Ordinary OAuth and personal-token connections cannot call those endpoints. Asana checks the actual token, organization license and resource permissions upstream.

Archiving a project alone contributes delete; combining it with an independent edit also contributes write. Overwriting an ordinary field is write. Webhook destinations and notifications contribute send. Membership, ownership, permission and organization settings carry admin where reviewed. Privilege grants, account security and general credential routes are refused by default and excluded from SDK methods. Mixed update routes refuse only their reviewed security-changing arguments. This contract contains no payment operations.

Assigning a task (including to yourself), adding followers, moving a task into a project or section, creating subtasks, and choosing the team for a new project are ordinary work actions. They do not grant account-management authority and are not permanently refused. Transferring project ownership is different: an owner can manage access, so that argument needs an explicit security allowance.

An organization admin can authorize a reviewed privilege change with a credential_minting policy scoped to the grant and exact operation. For every Asana credential, account-security or privilege allowance, the body must name one authenticated caller with caller_type (api_key or agent) and its metadata UUID in caller_id, plus a nonempty reason and an expires_at timestamp with a timezone. A broad rule binding never allows another caller. The allowance expires at that instant on every request, including when the rule body is cached. Other deny and approval rules still apply. The allowance does not make the operation an SDK method; use the raw proxy for the reviewed request.

{
"mode": "require_approval",
"provider": "asana",
"caller_type": "api_key",
"caller_id": "11111111-1111-4111-8111-111111111111",
"operations": ["asana:updateProject"],
"reason": "Transfer the project to its approved administrator.",
"expires_at": "2027-01-02T03:04:05Z"
}

Choose an expiry appropriate to the approved work and add the approval settings described in Set policies.

Sensitive input remains usable and is held encrypted for approvals, with masked approver displays. When a private value changes an operation’s effects, the approval shows the catalog’s full possible family set so its labels reveal no private branch. The inventory covers files, personal contact information, private text and dynamic custom-field selectors. A custom-field policy binds its operation, field GID, operator and operand together; duplicate or ambiguous keys cannot satisfy it. Selected custom-field values are masked because their tenant-defined meaning is unknown; field definitions and available options remain visible. Personal profile names are also masked. Payload capture follows the application’s setting and masks the shared inventory; binary bodies, credential outputs and raw card data are never captured. Temporary attachment/export URLs are narrow capabilities, marked secret_output without blocking the content operation.

Ordinary REST errors use HTTP failure statuses. Raw /batch calls classify each action independently, including its approval and quota checks. A wholly failed nonempty batch is a provider fault; partial successes retain their per-action results. The unrestricted batch action schema can also carry security operations, so batch has no typed SDK method. Attachment uploads, organization exports, SCIM and nested batches are not supported inside a batch, following Asana’s documented restrictions.

The pinned official source, its hash, the generated methods and the policy mapping are checked together. Scheduled checks save upstream candidates and report additions, removals and schema changes; they never replace a published contract automatically. Existing contract versions remain available for installed SDKs and pending approvals.

Persist call.approvalId (TypeScript) or call.approval_id (Python), then construct a fresh provider client and call resume(savedId), followed by wait(). The stored approval selects the operation; this installed package verifies its provider and contract version before attaching the response validator. Mismatches raise ManagedOperationError, never silently decode using another contract. See persist-and-resume examples.

Policy operation fields also accept the published SDK function IDs listed by alter integrations operations asana. Use when.operation for a json_match or conditional require_approval rule, or match.operations for content_match (including redaction and step-up). Conditional approval can also use when.match.operations with parameter conditions. alter policy simulate --operation <function-id> tests that exact function.

Managed calls carry a server-verified function identity. Alter still evaluates policy against the actual method, URL and body after building the request from the authorized connection. Existing endpoint, method, host, catalog-operation and family rules continue to apply unchanged. A raw call can share an endpoint with several SDK functions and matches all of them; a function name never grants permission or bypasses existing restrictions.

For example, this rule requires approval for one function:

{
"effect": "require_approval",
"when": { "operation": "asana.createtag" },
"approval": { "approvers": ["reviewer@example.com"] }
}

Save it with alter policy rules create --app <app-id> --grant <grant-id> --type require_approval --body @rule.json, or select the function in the portal.

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.