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¶

Go to Settings → API Keys
Click New API Key
Select the scopes your integration needs (see Scope Reference)
Copy the key — it is shown only once
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

Canviq issues three kinds of key, in two prefix families:

Key kind	Prefix	Created from	Accepted by
Org/REST	`pk_live_` / `pk_test_`	Settings → API Keys	`/api/v1/*`
Agent MCP	`pk_live_` / `pk_test_`	Settings → Agents	`/api/mcp`, the `canviq` CLI
SDK	`cvq_live_` / `cvq_test_`	Settings → API Keys	`/api/sdk/*`, the client-side SDK

The pk_ prefix does not tell org/REST and agent MCP keys apart

Those two share a prefix, so the only thing that distinguishes them is where you created it. The CLI and the MCP endpoint accept only an agent key created from Agent Management; an org/REST key created on the API Keys page will look valid and be rejected by /api/mcp. SDK keys are unambiguous by sight: they carry the cvq_ prefix, and the SDK endpoints reject a pk_ key before any lookup happens. See AI Agents → Authentication for the full key-type table.

Scope Reference¶

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

Scope	What it allows
`org:read`	Read org metadata, plan, board URL
`org:write`	Update org name, branding, allowed origins
`webhooks:write`	Register and manage webhook endpoints

There is no scope for creating submissions, voting, or commenting: no public REST endpoint exists for those actions today. See Votes API for the reasoning.

There is also no scope for inviting or managing team members. POST /api/admin/team is session-authenticated only and accepts no API key. Invite team members from Settings → Team in the admin dashboard instead.

Scope Guidance by Integration Type¶

Integration	Minimum scopes
Bot org provisioning	`org:read`, `org:write`
Webhook registration	`webhooks:write`

Bootstrap Tokens¶

!!! info "Coming soon" Token-authenticated org provisioning is not yet available. POST /api/organizations currently accepts only a browser onboarding_session cookie, so it cannot be driven from a script. There is no pk_bootstrap_ credential to request. Create your organization by signing up at canviq.app, then use an org API key from Settings → API Keys for everything after that.

The planned shape is a single-use, admin-issued token valid only for POST /api/organizations, returning a permanent org API key. See Bot / CI Onboarding for the rest of the provisioning flow and which of its steps work today.

Rotating a Key¶

If a key is compromised or no longer needed:

Go to Settings → API Keys
Find the key and click Rotate (or Revoke)
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 that only registers webhooks should only have webhooks: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.