Skip to content

Bot / CI Pipeline Onboarding

Provision a Canviq organization programmatically — from a CI pipeline, an internal admin script, or a multi-tenant automation.

When to Use This

  • You're building an internal tool that provisions Canviq boards for your customers
  • You want to set up a Canviq org as part of a CI/CD pipeline
  • You're testing Canviq with temporary orgs and want repeatable setup

For first-party org setup as a human user, use the onboarding wizard instead.

Prerequisites

You'll need a bootstrap token — a one-time, admin-issued credential that authorizes POST /api/organizations.

!!! info "Coming soon" Bootstrap tokens are not implemented yet. There is no credential to request, and the Canviq team cannot issue one manually. Create the organization by signing up at canviq.app, then start from Step 2 with an org API key from Settings → API Keys.

Step 1 — Create the Organization

!!! info "Coming soon" Scripted org creation is not yet available. POST /api/organizations accepts only a browser onboarding_session cookie, so the call below cannot be driven from a bot or a CI job today. It is recorded here as the planned shape.

curl -X POST https://canviq.app/api/organizations \
  -H "Authorization: Bearer pk_bootstrap_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme",
    "admin_email": "admin@acme.com"
  }'

Request Body

Field Type Required Description
name string Yes Organization display name (3–100 chars)
slug string Yes URL-safe board identifier — {slug}.canviq.app
admin_email string Yes Email address of the org owner

Response

{
  "org_id": "a1b2c3d4-...",
  "slug": "acme",
  "board_url": "https://acme.canviq.app/en",
  "api_key": "pk_live_...",
  "admin_magic_link": "https://canviq.app/api/auth/verify?token=..."
}

!!! warning "Save the API key now" The api_key is returned once. Store it immediately in your secrets manager. The admin_magic_link expires in 15 minutes.

The org is created with:

  • plan = 'trial' with 14-day trial
  • Creator assigned as owner in organization_members
  • Activation checklist started

Step 2 — Check Slug Availability

!!! info "Coming soon" GET /api/organizations/check-slug is not yet available. Until it ships, check for a slug_taken (409) response from Step 1 to detect conflicts.

Step 3 — Configure the Board

Use the returned api_key (scope: org:write) for all subsequent setup calls.

Add Categories

!!! info "Coming soon" POST /api/organizations/{id}/categories is not yet available. Categories can be added manually from the admin dashboard after first login.

Invite Team Members

!!! info "Coming soon" POST /api/admin/team is session-authenticated only and accepts no API key today, so it cannot be driven from a bot or CI job. Invite team members from Settings → Team in the admin dashboard after the org owner logs in via the magic link above.

Connect GitHub

!!! info "Coming soon" POST /api/organizations/{id}/integrations/github is not yet available. GitHub can be connected from Settings → Integrations after the org is created.

Set Trusted Redirect Origins (iOS / Android)

!!! info "Coming soon" PATCH /api/organizations/{id} for trusted redirect origins is not yet available. Configure this from Settings → General once it ships.

Full Provisioning Script

!!! warning "Partial — some steps not yet available" Slug availability check, category creation, team invites, and GitHub connection APIs are not yet shipped (see Step 2/3 above). The script below covers only the live endpoints. Remaining setup is done via the admin dashboard.

#!/usr/bin/env bash
# Requires: curl, jq (brew install jq)
set -euo pipefail

BOOTSTRAP_TOKEN="${CANVIQ_BOOTSTRAP_TOKEN}"
ORG_NAME="Acme Corp"
ORG_SLUG="acme"
ADMIN_EMAIL="admin@acme.com"

# 1. Create org
RESPONSE=$(curl -s -X POST https://canviq.app/api/organizations \
  -H "Authorization: Bearer $BOOTSTRAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"$ORG_NAME\", \"slug\": \"$ORG_SLUG\", \"admin_email\": \"$ADMIN_EMAIL\"}")

# Check for slug conflict
if echo "$RESPONSE" | jq -e '.error == "slug_taken"' > /dev/null 2>&1; then
  echo "Error: slug '${ORG_SLUG}' is already taken. Choose a different slug."
  exit 1
fi

ORG_ID=$(echo "$RESPONSE" | jq -r .org_id)
ORG_KEY=$(echo "$RESPONSE" | jq -r .api_key)
BOARD_URL=$(echo "$RESPONSE" | jq -r .board_url)
MAGIC_LINK=$(echo "$RESPONSE" | jq -r .admin_magic_link)

echo "Org created: $BOARD_URL"
echo "Admin magic link (expires 15 min): $MAGIC_LINK"

# 2. Store the API key securely (do this before anything else)
# In production, write to your secrets manager:
# aws secretsmanager put-secret-value --secret-id canviq/acme/api-key --secret-string "$ORG_KEY"

echo "Setup complete. Board URL: $BOARD_URL"
echo "Next: log in via the magic link above, then configure categories and GitHub from the admin dashboard."

Error Handling

Error Code Cause
slug_taken 409 Slug is already in use — choose a different one
invalid_slug 400 Slug contains invalid characters or is reserved
bootstrap_token_used 401 Token was already consumed
bootstrap_token_expired 401 Token expired (7-day TTL)
unauthorized 401 Token is invalid or malformed

After Setup

Once the org is provisioned:

  1. Deliver the admin_magic_link to admin_email — they use it for their first login
  2. The org enters a 14-day trial — contact support@canviq.app for details on trial limits and plan upgrades
  3. Direct users to https://{slug}.canviq.app/en to submit feedback