Integration and API Spec

Integration and API Spec

User Provisioning and Access Management

BambooHR is the authoritative trigger source for all provisioning and deprovisioning events. The automation platform registers a webhook endpoint in BambooHR that fires on any employee record status change. The payload is parsed to extract the employee ID, status, role, and department before the Provisioning Policy Agent proceeds.

// Webhook payload (abbreviated)
{
  "employeeId": "1042",
  "action": "changed",
  "fields": {
    "employmentStatus": { "oldValue": "Active", "newValue": "Terminated" }
  }
}
// Follow-up GET response fields consumed by Agent 1
id, firstName, lastName, jobTitle, department, location,
supervisorId, hireDate, terminationDate, employmentStatus,
customField_access_tier, customField_cost_centre

Okta is the central identity provider. Agent 1 creates or updates Okta user profiles and assigns group memberships on hire or transfer. Agent 2 immediately suspends and then deactivates the Okta account on termination. Group membership in Okta drives federated access to Google Workspace and Microsoft 365 where SAML or OIDC federation is configured.

// POST /api/v1/users?activate=true (hire)
{
  "profile": {
    "firstName": "{{firstName}}",
    "lastName": "{{lastName}}",
    "email": "{{workEmail}}",
    "login": "{{workEmail}}",
    "department": "{{department}}",
    "title": "{{jobTitle}}"
  },
  "groupIds": ["{{resolved_group_ids}}"]
}
// POST /api/v1/users/{userId}/lifecycle/suspend (offboarding step 1)
// POST /api/v1/users/{userId}/lifecycle/deactivate (offboarding step 2)

Google Workspace provisioning covers user account creation, organisational unit assignment, Google Group membership, and shared Drive access on hire. On offboarding, the account is suspended, Drive files are transferred to the line manager, and the mailbox is delegated or archived per the data retention policy agreed with legal.

// POST https://admin.googleapis.com/admin/directory/v1/users (hire)
{
  "primaryEmail": "{{workEmail}}",
  "name": { "givenName": "{{firstName}}", "familyName": "{{lastName}}" },
  "password": "{{generated_temp_password}}",
  "changePasswordAtNextLogin": true,
  "orgUnitPath": "{{resolved_ou_path}}"
}
// POST /admin/directory/v1/groups/{groupKey}/members (add to groups)
// POST https://www.googleapis.com/drive/v3/files/{fileId}/permissions (ownership transfer)
// POST /admin/directory/v1/users/{userKey} PATCH { "suspended": true } (offboarding)

Microsoft 365 integration handles licence assignment, Teams membership, and SharePoint site access on hire. On offboarding, the licence is removed, the user is removed from Teams groups, and the mailbox is placed on litigation hold or archived per the data retention policy. All Microsoft Graph API calls use the app-only Client Credentials flow.

// POST https://graph.microsoft.com/v1.0/users (hire)
{
  "displayName": "{{firstName}} {{lastName}}",
  "mailNickname": "{{mailNickname}}",
  "userPrincipalName": "{{workEmail}}",
  "usageLocation": "US",
  "accountEnabled": true,
  "passwordProfile": { "password": "{{generated_temp_password}}", "forceChangePasswordNextSignIn": true }
}
// POST /v1.0/users/{userId}/assignLicense (SKU assignment)
// POST /v1.0/groups/{groupId}/members/$ref (Teams/SharePoint)
// PATCH /v1.0/users/{userId} { "accountEnabled": false } (offboarding)

Slack is used for two purposes: operational actions (workspace invite, channel membership, deactivation on offboarding) and notifications (manager alerts on completion). The Slack bot token must have both user management and messaging scopes. Full deactivation via the SCIM API requires Slack Business+.

// POST https://slack.com/api/users.admin.invite (hire - requires admin token)
{ "email": "{{workEmail}}", "channels": "{{channel_ids_csv}}", "real_name": "{{fullName}}" }
// PATCH https://api.slack.com/scim/v2/Users/{userId} (offboarding)
{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "active": false }
// POST https://slack.com/api/chat.postMessage (manager notification)
{
  "channel": "{{manager_slack_id}}",
  "text": "Provisioning complete for {{fullName}}. All accounts actioned. Audit ticket: {{jira_ticket_url}}"
}

Jira is used exclusively by Agent 2 (Offboarding Audit Agent) to create timestamped audit tickets for every termination event. A separate issue type is used for elevated-permissions review requests, which Agent 1 raises when a non-standard access profile is detected. All calls use the Jira Cloud REST API v3.

// POST https://{JIRA_BASE_URL}/rest/api/3/issue (audit ticket creation)
{
  "fields": {
    "project": { "key": "{{JIRA_PROJECT_KEY}}" },
    "summary": "Offboarding Audit: {{fullName}} - {{terminationDate}}",
    "issuetype": { "name": "{{JIRA_ISSUE_TYPE_AUDIT}}" },
    "{{JIRA_FIELD_EMPLOYEE_ID}}": "{{employeeId}}",
    "{{JIRA_FIELD_SYSTEMS_ACTIONED}}": "Okta, Google Workspace, Microsoft 365, Slack",
    "{{JIRA_FIELD_DEACTIVATION_TIMESTAMPS}}": "{{deactivation_log_json}}",
    "description": {
      "type": "doc", "version": 1,
      "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "{{audit_narrative}}" }] }]
    }
  }
}

# BambooHR
BAMBOOHR_API_KEY          = <bamboohr_service_account_api_key>
BAMBOOHR_SUBDOMAIN        = <your_bamboohr_subdomain>
BAMBOOHR_WEBHOOK_SECRET   = <hmac_secret_from_bamboohr_webhook_config>

# Okta
OKTA_DOMAIN               = <yourorg>.okta.com
OKTA_CLIENT_ID            = <service_app_client_id>
OKTA_CLIENT_SECRET        = <service_app_client_secret>

# Google Workspace
GOOGLE_SA_KEY_JSON        = <service_account_json_key_contents>
GOOGLE_ADMIN_EMAIL        = <admin_user_to_impersonate@yourdomain.com>
GOOGLE_PRIMARY_DOMAIN     = <yourdomain.com>

# Microsoft 365
M365_TENANT_ID            = <azure_ad_tenant_id>
M365_CLIENT_ID            = <app_registration_client_id>
M365_CLIENT_SECRET        = <app_registration_client_secret>

# Slack
SLACK_BOT_TOKEN           = xoxb-<bot_token>
SLACK_SCIM_TOKEN          = <scim_api_token>
SLACK_WORKSPACE_ID        = T<workspace_id>

# Jira
JIRA_BASE_URL             = https://<yourorg>.atlassian.net
JIRA_EMAIL                = <service_account_email@yourdomain.com>
JIRA_API_TOKEN            = <jira_api_token>
JIRA_PROJECT_KEY          = ITAUDIT
JIRA_ISSUE_TYPE_AUDIT     = IT Audit Record
JIRA_ISSUE_TYPE_REVIEW    = Access Review
JIRA_FIELD_EMPLOYEE_ID    = customfield_10042
JIRA_FIELD_SYSTEMS_ACTIONED = customfield_10043
JIRA_FIELD_DEACTIVATION_TIMESTAMPS = customfield_10044

# Workflow config (not secrets, but stored centrally)
OU_ENGINEERING            = /corp/engineering
OU_SALES                  = /corp/sales
OU_OPERATIONS             = /corp/operations
GROUP_ID_ENGINEERING      = 00g1abc123def456
GROUP_ID_SALES            = 00g2abc123def456
SKU_BUSINESS_BASIC        = 3b555118-157b-4e84-9b7a-cbb6e7a18972
SKU_BUSINESS_PREMIUM      = cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46
SLACK_CHANNEL_ENGINEERING = C01ABCDEF12
SLACK_CHANNEL_SALES       = C01BCDEF123