Canva Typed REST Adapter
Overview
Treat the adapter as a transport boundary, not an authorization oracle or official Canva SDK. Keep policy and token rotation outside generic request methods, and tolerate documented non-breaking response additions.
Prerequisites
- Language/runtime, package policy, and required operations
- Pinned OpenAPI bytes/checksum and generation configuration
- Authorization, token, data, retry, and test boundaries
Instructions
Step 1: Select the minimal surface
Use Read and Grep to list only required operations, scopes, request/response shapes, async job states, and preview flags.
Step 2: Pin generation inputs
Store or checksum the OpenAPI contract and generator version. Review endpoint, scope, enum, validation, and preview changes before regeneration.
Step 3: Define adapter interfaces
Use Write or Edit to expose explicit operation methods, normalized errors, response validation, timeout context, and opaque request/job metadata.
Step 4: Keep policy outside
Require an already-authorized tenant/resource decision and token lease. Do not let a generic client select roles, broaden scopes, refresh concurrently, or log bodies.
Step 5: Handle responses safely
Validate required fields, accept additive unknown fields where the contract allows, reject unsafe type/status drift, and model in-progress/success/failed without exhaustive assumptions about preview enums.
Step 6: Constrain retries
Retry only classified safe reads or reconciled operations under a bounded policy. Return authorization and throttling facts to their owning layers.
Step 7: Test contract drift
Exercise fixtures for success, provider errors, unknown fields, changed enums, malformed bodies, timeouts, duplicate prevention, and redaction.
Authentication
Canva Connect calls use Bearer access tokens obtained by a backend through OAuth 2.0 Authorization Code with SHA-256 PKCE. Request explicit least-privilege scopes, keep client secrets and tokens out of browser-visible state, and serialize refresh so the replacement single-use refresh token is stored atomically.
Tool Discipline
Use Read and Grep for discovery and evidence. Use Write or Edit only for the approved artifact, code, configuration, test, or receipt described by this workflow; do not make an unapproved Canva-side change.
Output
- Scoped decision or implementation artifact
- Redacted operation and validation receipt
- Failure, rollback, and follow-up ownership record
Examples
A generated TypeScript transport covers users, designs, and exports, but an application service still owns tenant authorization, refresh serialization, operation identity, and result retention.
Error Handling
| Failure | Response |
|---|---|
| Generated diff changes scopes | Require authorization and consent review |
| Client auto-retries writes | Disable it and add operation reconciliation |
| Unknown response field breaks parsing | Adopt additive-safe validation where permitted |
| Adapter logs bodies or tokens | Block release and remediate |