Integration and API Spec

Integration and API Spec

Software Licence Management Automation

Queried by the Licence Discovery Agent (Agent 1) on a daily schedule to retrieve the current list of all user accounts (active and disabled) and their assigned licence SKUs. The integration uses application-level permissions so no interactive user sign-in is required at runtime.

// Output (to Licence Discovery Agent logic)
users[]: { id, displayName, userPrincipalName, accountEnabled, assignedLicenses[{ skuId, skuPartNumber }] }
// Pagination token
@odata.nextLink: string | null

Used by both agents. Agent 1 reads the licence register to compare against live Microsoft 365 data and writes flagged anomalies. Agent 2 reads flagged records, writes owner decisions back, and updates status fields and next review dates.

// Input (Agent 1 read)
GET /v1/databases/{NOTION_LICENCE_DB_ID}/query -> filter: { Renewal_Date within 60 days OR Status = 'Active' }
// Input (Agent 2 read)
GET /v1/databases/{NOTION_LICENCE_DB_ID}/query -> filter: { Status = 'Flagged' }
// Output (Agent 1 write)
PATCH /v1/pages/{page_id} -> { Status: 'Flagged', Last_Reviewed: today, Assigned_Agent: 'Renewal_Coordination_Agent' }
// Output (Agent 2 write)
PATCH /v1/pages/{page_id} -> { Decision, Decision_Notes, Status: 'Pending_Decision' | 'Renewed' | 'Cancelled', Next_Review_Date }

Used by Agent 2 (Renewal Coordination Agent) to send structured renewal alert messages to individual tool owners and to deliver the daily digest to the IT manager. Response capture from tool owners is handled via Slack interactive message callbacks or a linked external form where the owner is outside the workspace.

// Outbound: renewal alert
POST /api/chat.postMessage -> { channel: owner_slack_id, blocks: renewal_alert_template, text: fallback_text }
// Outbound: daily digest
POST /api/chat.postMessage -> { channel: SLACK_DIGEST_CHANNEL_ID, blocks: digest_summary_template }
// Inbound: owner response callback
POST {orchestration_webhook_endpoint} <- { payload: { actions[{ action_id, value }], user.id, message.ts, response_url } }
// Validate
X-Slack-Signature: v0=HMAC-SHA256(SLACK_SIGNING_SECRET, v0:{timestamp}:{body})

Used by Agent 2 to post a consolidated finance note to the relevant Xero contact or bill record after renewal decisions are collected. This gives the finance team a structured record of licence changes without requiring a separate email or manual entry.

// Output: finance note post
POST https://api.xero.com/api.xro/2.0/Contacts/{XERO_IT_CONTACT_ID}/Attachments
Headers: { Xero-Tenant-Id: XERO_TENANT_ID, Authorization: Bearer {access_token}, Content-Type: application/pdf }
Body: { filename: 'licence_change_note_{YYYY-MM-DD}.pdf', content: base64_encoded_note }
// Token refresh
POST https://identity.xero.com/connect/token
Body: { grant_type: refresh_token, refresh_token: XERO_REFRESH_TOKEN, client_id: XERO_CLIENT_ID, client_secret: XERO_CLIENT_SECRET }

// Credential store contents
// Microsoft 365
MS365_TENANT_ID          = '<azure-ad-tenant-id>'
MS365_CLIENT_ID          = '<azure-ad-app-client-id>'
MS365_CLIENT_SECRET      = '<azure-ad-app-client-secret>'

// Notion
NOTION_API_TOKEN         = 'secret_<internal-integration-token>'
NOTION_LICENCE_DB_ID     = '<notion-licence-register-database-id>'
NOTION_DECISIONS_DB_ID   = '<notion-renewal-decisions-log-database-id>'

// Slack
SLACK_BOT_TOKEN          = 'xoxb-<slack-bot-token>'
SLACK_SIGNING_SECRET     = '<slack-app-signing-secret>'
SLACK_IT_MANAGER_USER_ID = 'U<slack-user-id-of-it-manager>'
SLACK_DIGEST_CHANNEL_ID  = 'C<slack-channel-id-for-digest>'
SLACK_FALLBACK_FORM_URL  = 'https://<form-host>/renewal-response'

// Xero
XERO_CLIENT_ID           = '<xero-connected-app-client-id>'
XERO_CLIENT_SECRET       = '<xero-connected-app-client-secret>'
XERO_TENANT_ID           = '<xero-organisation-tenant-id>'
XERO_REFRESH_TOKEN       = '<xero-oauth2-refresh-token>'
XERO_IT_CONTACT_ID       = '<xero-contact-id-for-it-cost-centre>'

// Orchestration configuration
ENV_TIMEZONE             = 'Australia/Sydney'   // adjust to business timezone
ENV_BUSINESS_HOURS_START = '08:00'
ENV_BUSINESS_HOURS_END   = '18:00'
ENV_RENEWAL_WINDOW_DAYS  = '60'
ENV_ALERT_RETRY_MAX      = '3'
ENV_ALERT_RETRY_BACKOFF_MIN = '5'