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_live_<43-char-secret>

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_live_ Production Live integrations
pk_test_ Sandbox Development and testing

!!! note "The prefix alone does not tell you what a key is for" Canviq issues three kinds of key (org/REST, SDK, and agent MCP), and all three share this same pk_live_/pk_test_ format. You cannot distinguish them by looking at the string. What tells you which one you have is where you created it: this page (Settings → API Keys) issues org/REST keys, the SDK page issues SDK keys, and the Agent Management page issues agent MCP keys. See AI Agents → Authentication for the full key-type table, and note in particular that the CLI and the MCP tools API only accept an agent MCP key created from Agent Management. A key created here or on the SDK page will authenticate to different endpoints but be rejected by /api/mcp/tools.

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 support@canviq.app 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.