REST API (Direct)¶

This guide shows how to integrate with the Contio Partner API using direct HTTP requests. For SDK-based integration, see the Quick Start guide.

Base URL¶

Prerequisites¶

Contact partner-support@contio.ai to obtain:

• Client ID and Client Secret (for OAuth 2.0 user operations)
• API Key (for admin operations)

Choose Your Integration Path¶

The Partner API uses two distinct authentication patterns, each designed for a specific context:

Path A: User Data Access (OAuth 2.0)¶

Use OAuth 2.0 to access user meetings and action items on behalf of connected users.

Step 1: Redirect User to Authorization¶

Construct the authorization URL and redirect the user:

https://api.contio.ai/oauth2/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://your-app.com/callback&
  scope=openid profile meetings:read action-items:read&
  state=RANDOM_STATE_FOR_CSRF

Step 2: Exchange Authorization Code for Tokens¶

After the user authorizes, they're redirected to your callback with a code parameter.

Client credentials must be provided via HTTP Basic authentication (Base64-encoded client_id:client_secret):

# Encode credentials: echo -n "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" | base64
curl -X POST https://api.contio.ai/oauth2/token \
  -H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://your-app.com/callback"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIi...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "openid profile meetings:read action-items:read"
}

Step 3: Make API Calls with Access Token¶

Include the access token in the Authorization header:

# Get user's meetings
curl -X GET "https://api.contio.ai/v1/partner/user/meetings?limit=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response:

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Weekly Team Sync",
      "scheduled_start": "2024-01-15T10:00:00Z",
      "scheduled_end": "2024-01-15T11:00:00Z",
      "status": "completed"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

Step 4: Refresh Tokens¶

Access tokens expire after 24 hours. Use the refresh token to get new tokens:

curl -X POST https://api.contio.ai/oauth2/token \
  -H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"

Path B: Admin Operations (API Key)¶

Use API key authentication for server-to-server admin operations.

Required Headers¶

Example: Get Partner App Info¶

curl -X GET https://api.contio.ai/v1/partner/admin/app \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-ID: YOUR_CLIENT_ID" \
  -H "Accept: application/json"

Response:

{
  "id": "app_abc123",
  "name": "My Partner App",
  "status": "active",
  "webhook_enabled": true,
  "webhook_url": "https://example.com/webhooks"
}

Example: List Automations¶

curl -X GET https://api.contio.ai/v1/partner/admin/automations \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-ID: YOUR_CLIENT_ID" \
  -H "Accept: application/json"

Example: Create an Automation¶

curl -X POST https://api.contio.ai/v1/partner/admin/automations \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-ID: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM Sync",
    "description": "Sync action items to our CRM",
    "trigger_type": "action_item_created",
    "actions": [{
      "type": "webhook",
      "webhook_url": "https://your-app.com/webhooks/contio"
    }]
  }'

Error Handling¶

The API returns consistent error responses across all endpoints. Every error response includes a request_id for support troubleshooting.

Partner API Error Format¶

{
  "error": "Human-readable error message",
  "code": "error_code",
  "request_id": "abc123xyz"
}

OAuth Error Format (RFC 6749)¶

OAuth endpoints return standard OAuth 2.0 error responses:

{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired"
}

Common Error Codes¶

Handling Authentication Errors¶

# Example: Missing API Key
curl -X GET https://api.contio.ai/v1/partner/admin/app \
  -H "X-Client-ID: YOUR_CLIENT_ID"

# Response (401):
{
  "error": "Missing API key",
  "code": "missing_api_key",
  "request_id": "req_abc123"
}

# Example: Expired Access Token
curl -X GET https://api.contio.ai/v1/partner/user/meetings \
  -H "Authorization: Bearer EXPIRED_TOKEN"

# Response (401):
{
  "error": "Invalid or expired access token",
  "code": "unauthorized",
  "request_id": "req_xyz789"
}

Rate Limits¶

Rate limits are enforced per IP address over a rolling 5-minute window.

When rate limited, the API returns:

{
  "error": "rate_limit_exceeded",
  "error_description": "Too many requests. Please retry after the rate limit window resets."
}

Webhook Verification¶

When receiving webhooks, always verify the signature to ensure the request came from Contio.

Webhook Headers¶

Signature Verification Algorithm¶

1. Get the raw request body (before JSON parsing)
2. Concatenate: timestamp + "." + body
3. Compute HMAC-SHA256 using your webhook secret
4. Compare with the provided signature

Python Example:

import hmac
import hashlib
import time

def verify_webhook(body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    # Check timestamp is within 5 minutes to prevent replay attacks
    if abs(time.time() - int(timestamp)) > 300:
        return False

    # Compute expected signature
    message = f"{timestamp}.{body.decode('utf-8')}"
    expected = hmac.new(
        secret.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    # Constant-time comparison
    return hmac.compare_digest(expected, signature)

Node.js Example:

const crypto = require('crypto');

function verifyWebhook(body, signature, timestamp, secret) {
  // Check timestamp is within 5 minutes
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    return false;
  }

  // Compute expected signature
  const message = `${timestamp}.${body}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');

  // Constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Next Steps¶

• Authentication Guide - Deep dive into OAuth 2.0 and API key configuration
• Webhook Events - Real-time event notifications
• API Reference - Complete endpoint documentation