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.

Contact [email protected] to request one. Tokens expire in 7 days and are single-use.

!!! info "Admin UI coming soon" Bootstrap token self-service is coming soon. Until it ships, tokens are issued manually by the Canviq team.

Step 1 — Create the Organization¶

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": "[email protected]"
  }'

Request Body¶

Response¶

{
  "org_id": "a1b2c3d4-...",
  "slug": "acme",
  "board_url": "https://acme.canviq.app/en",
  "api_key": "pk_org_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¶

curl -X POST https://canviq.app/api/admin/team \
  -H "Authorization: Bearer $ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role": "admin"
  }'
# Returns: { "status": "invite_sent", "email": "[email protected]" }
# The invite link is emailed directly to the invitee — it is not returned in the API response.

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, 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="[email protected]"

# 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¶

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 [email protected] for details on trial limits and plan upgrades
3. Direct users to https://{slug}.canviq.app/en to submit feedback