Platform integration quickstart

This guide covers the Clearnote and Docsum style flow: provision client workspaces under your platform org and send envelopes scoped to each client with webhooks and correlation IDs.

Structured docs:

• Platform overview: five-minute setup with diagrams
• Connected accounts
• Webhooks and debugging
• Billing modes
• Platform via MCP and API
• FAQ

Prerequisites

• Atlas org admin access on your partner workspace
• A platform API key (not a profile API key)
• PLATFORM_TENANCY must not be hard-off in your Atlas environment (contact Atlas if sends fail with platform disabled)

1. Create a platform API key

In the dashboard: Platform tab → create a platform API key.

Platform keys live in api_keys with platform_org_id set. Profile keys cannot send Atlas-Account.

2. Provision a connected account

Each end customer gets an isolated workspace (org, credits pool, teams). Provisioning is idempotent on external_id.

POST /api/platform/connected-accounts
Authorization: Bearer <platform_api_key>
Content-Type: application/json

{
  "external_id": "acme-corp-42",
  "name": "Acme Corp",
  "billing_mode": "platform_pays",
  "initial_credits": 10
}

Response:

{
  "success": true,
  "connected_org_id": "uuid",
  "external_id": "acme-corp-42",
  "created": true,
  "next_step": "Create envelopes with Atlas-Account: ext_<external_id> or the connected org UUID."
}

billing_mode options:

List clients:

GET /api/platform/connected-accounts
Authorization: Bearer <platform_api_key>

3. Create and send on behalf of a client

Pass Atlas-Account on every envelope and template call:

Atlas-Account: ext_acme-corp-42

Or use the bare connected org UUID from the provision response.

Upload (review-first)

curl -X POST https://atlaswork.ai/api/envelope \
  -H "Authorization: Bearer $PLATFORM_API_KEY" \
  -H "Atlas-Account: ext_acme-corp-42" \
  -F "file=@contract.pdf" \
  -F 'parties=[{"email":"signer@client.com","name":"Jane Signer","order":1}]' \
  -F 'metadata={"client_reference_id":"matter-9912"}'

Open review_url, verify fields, then send:

POST /api/envelope/{id}/send
Authorization: Bearer <platform_api_key>
Atlas-Account: ext_acme-corp-42

Auto-send at create (API only)

Add auto_send: true on create when you skip human review. Same headers apply.

4. Correlate sends with your CRM

Store your matter or tenant ID on the envelope:

{
  "metadata": {
    "client_reference_id": "matter-9912",
    "external_id": "docsum-task-884"
  }
}

Both keys are allowlisted customer metadata. Filter your sends later:

GET /api/envelopes?external_id=matter-9912
Authorization: Bearer <platform_api_key>
Atlas-Account: ext_acme-corp-42

Matches metadata.client_reference_id or metadata.external_id.

5. Webhooks

Set webhook_url at create time (form field or JSON). Atlas POSTs on lifecycle events (envelope.sent, envelope.signed, contract.extracted, etc.).

Verify the X-Atlas-Signature header:

sha256=HMAC-SHA256(JSON.stringify(payload), your_api_key)

Node.js example:

const crypto = require('crypto');

function verifyAtlasWebhook(rawBody, signatureHeader, apiKey) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', apiKey)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected),
  );
}

Use the raw request body bytes, not re-serialized JSON, if your framework gives you the raw buffer.

6. Suspend a client

PATCH /api/platform/connected-accounts/{connected_org_id}
Authorization: Bearer <platform_api_key>
Content-Type: application/json

{ "status": "suspended" }

Suspended accounts return 403 account_suspended on send. Drafts and reads still work.

7. Dashboard visibility

Org admins can see platform status and connected accounts under Platform in the dashboard. Full client lifecycle remains API-driven.

Common mistakes

Reference

• Platform guides: docs/platform/index.md
• Human docs index: docs/platform/index.md
• Agent index: https://atlaswork.ai/llms.txt
• Postman: import public/atlas-api.postman_collection.json, open the Platform folder