Canva Integration

The Canva integration allows users to import designs from their Canva account directly into the platform's image library. It uses OAuth 2.0 for authentication and the Canva Connect API for accessing designs and assets.

Authentication

We use the OAuth 2.0 Authorization Code Flow to authenticate users with Canva.

Configuration

The following environment variables are required:

• CANVA_CLIENT_ID: Your Canva App Client ID
• CANVA_CLIENT_SECRET: Your Canva App Client Secret
• CANVA_REDIRECT_URI: The callback URL (e.g., https://your-domain.com/api/oauth/canva/callback)

Scopes

The integration requests the following scopes:

• design:content:read: To read design content
• design:content:write: To create/update designs (for future use)
• asset:read: To read assets from the user's library
• asset:write: To upload assets to the user's library

OAuth Flow

1. Authorization Request: User is redirected to https://www.canva.com/api/oauth/authorize.
2. Callback: Canva redirects back to /api/oauth/canva/callback with an authorization code.
3. Token Exchange: The backend exchanges the code for an access_token and refresh_token at https://api.canva.com/oauth/token.
4. Storage: Tokens are stored in the Account table in the database, linked to the user.

API Endpoints (tRPC)

The canvaRouter provides the following procedures:

getDiagnostics

• Type: Query
• Description: Checks connection status and returns basic account info (design count, folders).
• Usage: Used on the Settings page to verify the integration.

listDesigns

• Type: Query
• Input: { limit: number, query?: string, folderId?: string, continuation?: string }
• Description: Lists designs from the user's Canva account. Supports pagination.

getDesign

• Type: Query
• Input: { designId: string }
• Description: Gets details for a specific design.

importDesign

• Type: Mutation
• Input: { designId: string, format?: 'png' | 'jpg' | 'pdf', quality?: 'high', ... }
• Description:
  1. Triggers a design export on Canva.
  2. Polls for completion.
  3. Downloads the exported file.
  4. Uploads it to our storage (MinIO).
  5. Creates an Image record in the database.

syncDesign

• Type: Mutation
• Input: { imageId: string }
• Description: Checks if a previously imported design has been updated on Canva. If so, re-imports it.

listAssets

• Type: Query
• Input: { type: 'IMAGE' | 'VIDEO' | 'AUDIO', limit: number, continuation?: string }
• Description: Lists assets (images, videos) from the user's Canva asset library.

uploadAsset

• Type: Mutation
• Input: { name: string, imageUrl: string, tags?: string[] }
• Description: Uploads an image from our platform to the user's Canva asset library.

Data Models

Integration Status

Status is tracked in the Integrations table:

• canva: Boolean (true if connected)

Tokens

Tokens are stored in the Account table:

• provider: "canva"
• providerAccountId: Canva User ID
• access_token: valid for 4 hours
• refresh_token: valid indefinitely (until revoked)
• expires_at: Timestamp of token expiration

Error Handling

• 401 Unauthorized: Automatically attempts to refresh the access token. If refresh fails, throws UNAUTHORIZED code, prompting the user to reconnect.
• 429 Too Many Requests: Implements exponential backoff retry logic.