Integration and API Spec

Integration and API Spec

Device and Hardware Management

Serves as the live device asset register. The orchestration layer reads and writes records in the Devices base via the Airtable REST API v0. All three agents interact with Airtable: Agent 1 queries and writes assignment and return records; Agent 3 writes MDM status back after Jamf calls.

// Query: find available device by spec
GET /v0/{AIRTABLE_BASE_ID}/Devices
  ?filterByFormula=AND({status}='Available',{device_type}='{requested_type}')
  &maxRecords=1
// Write: assignment record update
PATCH /v0/{AIRTABLE_BASE_ID}/Devices/{recordId}
  body: { fields: { assigned_to, assignment_date, expected_return_date, status, jira_ticket_id } }
// Output: updated record object with all field values

Used by Agent 1 (Asset Register Agent) to create and update IT service tickets for every device event, ensuring an audit trail independent of the Airtable register. Jira is also the primary inbound trigger for device request events.

// Inbound webhook payload (trigger)
POST {orchestration_inbound_url}/jira-webhook
  headers: { X-Hub-Signature: 'sha256={hmac}' }
  body: { issue: { id, key, fields: { summary, status, assignee, customfield_device_serial } } }
// Create ticket
POST /rest/api/3/issue
  body: { fields: { project: {key}, issuetype: {id}, summary, description, customfield_device_serial } }
// Transition ticket status
POST /rest/api/3/issue/{issueId}/transitions
  body: { transition: { id: '{JIRA_TRANSITION_ID_ASSIGNED}' } }

Used exclusively by Agent 3 (MDM Sync Agent) to verify device enrollment, apply policy profiles on assignment, and trigger remote wipe on returned devices. Jamf is the highest-risk integration: wipe calls are irreversible and must be gated by a confirmation check against the Airtable record before execution.

// Get Bearer token
POST {JAMF_BASE_URL}/api/v1/auth/token
  headers: { Authorization: 'Basic {base64(JAMF_API_USER:JAMF_API_PASSWORD)}' }
  response: { token, expires }
// Verify enrollment
GET {JAMF_BASE_URL}/api/v1/computers-preview?filter=serialNumber=={device_serial}
  headers: { Authorization: 'Bearer {token}' }
  response: { results: [{ id, serialNumber, managementStatus, policyIds }] }
// Trigger remote wipe (IRREVERSIBLE - confirm Airtable status before calling)
POST {JAMF_BASE_URL}/api/v1/computers-preview/{computerId}/erase
  body: { pin: '{JAMF_WIPE_PIN}' }
// Poll wipe status
GET {JAMF_BASE_URL}/api/v1/computers-preview/{computerId}
  until managementStatus == 'Erased'

Used by Agent 2 (Device Lifecycle Comms Agent) to send all outbound emails: assignment confirmations, quarterly audit requests, overdue return reminders, and procurement alerts. All emails use stored templates with dynamic field substitution from Airtable record data.

// Send email via Gmail API
POST https://gmail.googleapis.com/gmail/v1/users/{GMAIL_SENDER_ADDRESS}/messages/send
  headers: { Authorization: 'Bearer {google_access_token}' }
  body: { raw: '{base64url_encoded_RFC2822_message}' }
// Template substitution (orchestration layer, before API call)
template = TEMPLATE_ASSIGNMENT_CONFIRMATION
  .replace('{{employee_name}}', airtable_record.assigned_to_name)
  .replace('{{device_serial}}', airtable_record.device_serial)
  .replace('{{device_type}}', airtable_record.device_type)
  .replace('{{expected_return_date}}', airtable_record.expected_return_date)
// Inbound: Pub/Sub push to orchestration endpoint
POST {orchestration_inbound_url}/gmail-pubsub
  body: { message: { data: base64(gmail_notification), messageId, publishTime } }

Used by Agent 2 (Device Lifecycle Comms Agent) to post alerts to the IT channel and direct messages to the IT manager. Covers procurement prompts when no device is available and post-assignment summaries.

// Post to IT channel
POST https://slack.com/api/chat.postMessage
  headers: { Authorization: 'Bearer {SLACK_BOT_TOKEN}' }
  body: {
    channel: '{SLACK_IT_CHANNEL_ID}',
    blocks: [{TEMPLATE_SLACK_ASSIGNMENT_SUMMARY substituted with event data}]
  }
// DM to IT manager (procurement alert)
POST https://slack.com/api/chat.postMessage
  body: {
    channel: '{SLACK_IT_MANAGER_USER_ID}',
    blocks: [{TEMPLATE_SLACK_PROCUREMENT substituted with requested_device_type, requestor_name}]
  }

Used as a fallback HR data sync source by Agent 1 when no native HR webhook is available. A scheduled daily poll reads a shared sheet maintained by the HR or operations team for new hire and departure events not yet captured in Jira.

// Read new HR events
GET https://sheets.googleapis.com/v4/spreadsheets/{GSHEETS_SPREADSHEET_ID}/values/{GSHEETS_SHEET_NAME}
  headers: { Authorization: 'Bearer {google_access_token}' }
// Filter unprocessed rows in orchestration layer
rows.filter(row => row.processed_by_automation === 'FALSE')
// Output per row: { event_type, employee_name, employee_email, start_date, device_type_requested }

// Credential store inventory — Device and Hardware Management automation
// All entries stored in the orchestration platform encrypted credential store

// Airtable
AIRTABLE_PAT                        // Personal Access Token, scoped to Devices base
AIRTABLE_BASE_ID                    // e.g. appXXXXXXXXXXXXXX

// Jira
JIRA_CLIENT_ID                      // Atlassian OAuth 2.0 app client ID
JIRA_CLIENT_SECRET                  // Atlassian OAuth 2.0 app client secret
JIRA_REFRESH_TOKEN                  // Long-lived refresh token (rotated on expiry)
JIRA_BASE_URL                       // e.g. https://yourcompany.atlassian.net
JIRA_PROJECT_KEY                    // IT
JIRA_ISSUE_TYPE_ID                  // Resolved at build time, stored as string
JIRA_TRANSITION_ID_ASSIGNED         // Resolved at build time, stored as string
JIRA_TRANSITION_ID_CLOSED           // Resolved at build time, stored as string
JIRA_WEBHOOK_SECRET                 // Shared secret for HMAC-SHA256 validation
JIRA_WEBHOOK_ENABLED                // Boolean flag: true/false

// Jamf Pro
JAMF_BASE_URL                       // e.g. https://yourcompany.jamfcloud.com
JAMF_API_USER                       // API role username (not admin account)
JAMF_API_PASSWORD                   // API role password
JAMF_POLICY_PROFILE_ID_STANDARD     // Policy profile ID applied on assignment
JAMF_CATEGORY_ASSIGNED              // Jamf category string for assigned devices
JAMF_CATEGORY_AVAILABLE             // Jamf category string for available devices
JAMF_WIPE_PIN                       // 6-digit PIN required for erase API call

// Gmail
GMAIL_SERVICE_ACCOUNT_KEY_JSON      // Google service account key (JSON, base64-encoded)
GMAIL_SENDER_ADDRESS                // e.g. it@yourcompany.com
GMAIL_PUBSUB_TOPIC                  // Google Cloud Pub/Sub topic name
GMAIL_LABEL_DEVICE_AUTOMATION       // Gmail label ID (not display name)

// Email templates (stored as config, not secrets, but in credential store for consistency)
TEMPLATE_ASSIGNMENT_CONFIRMATION    // HTML string with {{field_name}} placeholders
TEMPLATE_AUDIT_REQUEST              // HTML string with {{field_name}} placeholders
TEMPLATE_OVERDUE_REMINDER           // HTML string with {{field_name}} placeholders
TEMPLATE_PROCUREMENT_ALERT          // HTML string with {{field_name}} placeholders

// Slack
SLACK_BOT_TOKEN                     // xoxb- prefixed bot token
SLACK_IT_CHANNEL_ID                 // Channel ID (not display name)
SLACK_IT_MANAGER_USER_ID            // User ID (not display name)
SLACK_SIGNING_SECRET                // For future interactive component validation
TEMPLATE_SLACK_PROCUREMENT          // Block Kit JSON string
TEMPLATE_SLACK_ASSIGNMENT_SUMMARY   // Block Kit JSON string

// Google Sheets (fallback)
GSHEETS_SERVICE_ACCOUNT_KEY_JSON    // Reuse Gmail service account where possible
GSHEETS_SPREADSHEET_ID              // Spreadsheet ID from URL
GSHEETS_SHEET_NAME                  // e.g. HR_Events