Skip to content

Authentication

Canviq supports two credential types depending on how your integration works.

Session Cookies (Browser)

Used when your users interact with the Canviq board directly in a browser, SFSafariViewController (iOS), or Chrome Custom Tabs (Android).

Canviq's magic link auth handles the full session lifecycle — no API key is needed on the client side. When a user authenticates, a signed, encrypted session cookie is set for canviq.app.

When to use: iframe embeds, in-app browsers, direct board links.

Org API Keys

Used for server-to-server calls, SDK integrations, and CI/CD pipelines.

Authorization: Bearer pk_org_live_<32-hex-chars>

Generating a Key

  1. Go to Settings → API Keys
  2. Click New API Key
  3. Select the scopes your integration needs (see Scope Reference)
  4. Copy the key — it is shown only once
  5. Store it in your secrets manager (AWS Secrets Manager, 1Password, Doppler, etc.)

!!! warning "Keys are shown once" If you lose a key, rotate it immediately from Settings → API Keys → Rotate.

Key Format

Prefix Environment Use
pk_org_live_ Production Live integrations
pk_org_test_ Sandbox (coming soon) Development and testing

Scope Reference

Scopes are granted at key creation time. Request only what your integration needs.

Scope What it allows
submissions:write Create submissions on behalf of users
submissions:read List and read submissions
members:read List org members
members:write Invite team members
org:read Read org metadata, plan, board URL
org:write Update org name, branding, allowed origins
webhooks:write Register and manage webhook endpoints

Scope Guidance by Integration Type

Integration Minimum scopes
Submit feedback from your app submissions:write
Read submissions for analytics submissions:read
Bot org provisioning org:read, org:write, submissions:write, members:write
Webhook registration webhooks:write

Bootstrap Tokens

For automated org provisioning (one-time setup, not ongoing calls), Canviq issues bootstrap tokens.

Authorization: Bearer pk_bootstrap_<32-hex-chars>

Bootstrap tokens:

  • Are admin-issued (contact [email protected] or use the Canviq admin panel)
  • Are single-use and expire after 7 days
  • Are only valid for POST /api/organizations
  • Return a permanent org API key upon successful use

See Bot / CI Onboarding for the full provisioning flow.

Rotating a Key

If a key is compromised or no longer needed:

  1. Go to Settings → API Keys
  2. Find the key and click Rotate (or Revoke)
  3. Update your secret store with the new key

Rotation invalidates the old key immediately. All in-flight requests using the old key will return 401.

Security Best Practices

  • Never expose API keys client-side. Keys must only be used server-to-server or in secure CI environments.
  • Use the minimum scope. A key for submission forwarding should only have submissions:write.
  • Rotate periodically. Rotate keys quarterly or immediately after a suspected exposure.
  • Audit key usage. Key usage is logged per-request. Contact support for audit exports.