Skip to content

Quick Start

This guide will help you make your first API call within minutes.

Prerequisites

  1. Partner Credentials: Contact partner-support@contio.ai to obtain:

    1. Client ID and Client Secret (for OAuth 2.0)
    2. API Key (for admin operations)

  2. SDK Installed: See Installation

Choose Your Integration Path

Path A: User Data Access (OAuth 2.0)

If you need to access user meetings and action items:

// quickstart-oauth.ts
import crypto from 'crypto';
import { ContioPartnerSDK } from '@contio/partner-sdk';

async function main() {
  // 1. Initialize the SDK
  const { oauth, user } = ContioPartnerSDK.forUser({
    clientId: process.env.CONTIO_CLIENT_ID!,
    clientSecret: process.env.CONTIO_CLIENT_SECRET!,
    redirectUri: 'https://your-app.com/callback'
  });

  // 2. Generate the authorization URL
  const state = crypto.randomUUID();
  const authUrl = oauth.getAuthorizationUrl(state);
  console.log('Open this URL in your browser to authorize:');
  console.log(authUrl);

  // 3. After user authorizes, exchange the code for tokens
  // (The code and state come from the callback URL query parameters)
  const code = 'AUTH_CODE_FROM_CALLBACK';
  const returnedState = 'STATE_FROM_CALLBACK';

  if (returnedState !== state) {
    throw new Error('Invalid OAuth state');
  }

  const tokens = await oauth.exchangeCodeForToken(code);
  console.log('Access token obtained:', tokens.access_token.slice(0, 20) + '...');

  // 4. Fetch user meetings
  const meetings = await user.getMeetings();
  console.log(`Found ${meetings.total} meetings`);

  for (const meeting of meetings.items) {
    console.log(`- ${meeting.title} (${meeting.status})`);
  }
}

main().catch(console.error);

OAuth Flow

The user must complete the full OAuth flow: enter their email, verify via OTP, and grant consent. Only then will they be redirected back with an authorization code.

Path B: Admin Operations (API Key)

If you need to manage workflows and webhooks:

// quickstart-admin.ts
import { ContioPartnerSDK } from '@contio/partner-sdk';

async function main() {
  // Initialize for admin operations
  const { admin } = ContioPartnerSDK.forAdmin({
    apiKey: process.env.CONTIO_API_KEY!
  });

  // Get partner app statistics
  const stats = await admin.getStats();
  console.log('Connected users:', stats.connected_users);
  console.log('Active workflows:', stats.active_workflows);

  // List all workflows
  const workflows = await admin.getWorkflows();
  console.log(`\nFound ${workflows.length} workflows:`);

  for (const workflow of workflows) {
    console.log(`- ${workflow.name} (${workflow.is_active ? 'active' : 'inactive'})`);
  }
}

main().catch(console.error);

Run with:

CONTIO_API_KEY=your_api_key npx ts-node quickstart-admin.ts

Set Up Webhooks

Receive real-time notifications when action items match your workflows.

Verifying Webhook Signatures

// verify-webhook.ts
import { WebhookVerifier } from '@contio/partner-sdk';

// Example webhook payload (received from Contio)
const payload = Buffer.from('{"type":"action_item.created","data":{...}}');
const signature = 'sha256=abc123...';  // From X-Contio-Signature header
const timestamp = '1234567890';         // From X-Contio-Timestamp header

const verifier = new WebhookVerifier(process.env.WEBHOOK_SECRET!);
const result = verifier.verifySignature(payload, signature, timestamp);

if (result.isValid) {
  const event = JSON.parse(payload.toString());
  console.log('Valid webhook received:', event.type);
} else {
  console.error('Invalid signature:', result.error);
}

Processing Webhook Events

// process-webhook.ts
import { WebhookEvent } from '@contio/partner-sdk';

function handleWebhook(event: WebhookEvent) {
  switch (event.type) {
    case 'workflow.assignment.created':
      console.log('New assignment:', event.data.action_item.title);
      console.log('Assigned to:', event.data.action_item.assigned_to_user_id);
      break;

    case 'action_item.updated':
      console.log('Action item updated:', event.data.id);
      console.log('New status:', event.data.status);
      break;

    default:
      console.log('Unhandled event type:', event.type);
  }
}

For a complete webhook server implementation, see the Webhook Events Guide.

Next Steps