FS-DOC-05Technical
Integration and API Spec
Password Reset & Access Requests
[YourCompany.com] · IT Department · Prepared by FullSpec · [Today's Date]
This document is the authoritative technical reference for every integration in the Password Reset and Access Requests automation. It covers the full tool inventory, exact OAuth scopes, webhook configurations, field mappings between agents, credential store layout, and error-handling requirements. The FullSpec team uses this document to build, configure, and validate all connections. No integration should be wired to a production credential before the sandbox validation steps in Section 01 are complete.
01Tool inventory
Tool
Role in automation
Auth method
Min plan required
Used by agents
Slack
Request intake via slash command; manager approval messages; requester notifications
OAuth 2.0 (Bot Token)
Pro (for Workflow Builder and slash commands)
Agent 1, Agent 2, Agent 3
Jira
Auto ticket creation, status updates, audit log closure
OAuth 2.0 or API Token (Basic Auth)
Standard (Cloud; REST API v3)
Agent 1, Agent 3
Okta
Identity challenge for password resets; user password reset API; role/group assignment
OAuth 2.0 (SSWS API Token or service app)
Workforce Identity (Developer Org acceptable for sandbox)
Agent 2, Agent 3
Google Workspace
Group membership updates; shared drive access grants
OAuth 2.0 (Service Account with domain-wide delegation)
Business Starter or above; Admin SDK enabled
Agent 3
Microsoft Azure AD
Directory source of record; reporting-line lookups for manager routing
OAuth 2.0 (Client Credentials flow)
Microsoft Entra ID P1 or above
Agent 2
Automation platform
Orchestration layer; credential store; workflow routing and retry logic
N/A (internal)
As selected during build
All agents
Before you connect anything: provision sandbox or developer-tier accounts for every tool listed above and validate all credentials and scopes in a non-production environment. Do not supply production API tokens or service account keys until end-to-end testing in Section 04 of the Test and QA Plan is passed. Sandbox credentials must be stored separately from production credentials in the credential store.
02Per-tool integration detail
Slack
Used across all three agents. Agent 1 receives the slash command trigger and web-form payload. Agent 2 posts manager approval interactive messages and listens for button-action callbacks. Agent 3 sends confirmation DMs to the requester.
Auth method
OAuth 2.0, Bot Token (xoxb-*). Install a Slack App to the workspace under a dedicated service identity. Store the Bot Token and Signing Secret in the credential store only.
Required scopes
commands, chat:write, chat:write.public, im:write, users:read, users:read.email, channels:read, app_mentions:read, reactions:write, files:write
Webhook / trigger setup
Register a slash command (e.g. /access-request) pointing to the orchestration layer's inbound webhook URL. Enable Interactivity and Shortcuts, setting the Request URL to the orchestration layer's interaction handler endpoint. All incoming payloads must have their X-Slack-Signature header validated against the Signing Secret using HMAC-SHA256 before processing.
Required configuration
Slash command name and description stored as environment variables, not hardcoded. Approval message block kit templates stored as named templates in the credential store. The IT escalation channel ID stored as SLACK_ESCALATION_CHANNEL_ID. Manager DM logic relies on the Azure AD manager lookup result.
Rate limits
Tier 3 methods (chat.postMessage): 50 requests/minute per workspace. At 60 requests/month, peak is approximately 3 to 5 Slack API calls per request run. Throttling is not required at current volume, but the orchestration layer should implement a 1.2-second delay between sequential chat.postMessage calls within the same workflow run to stay well within limits.
Constraints
Interactive button payloads expire after 30 minutes by default. The approval message must include an explicit expiry timestamp and the Agent 2 reminder logic must fire before this window closes. Slash commands only work for users who are active workspace members.
Jira (Cloud REST API v3)
Used by Agent 1 to create tickets and by Agent 3 to update, comment, and close them. All Jira interactions use the Cloud REST API v3 base URL: https://<your-domain>.atlassian.net/rest/api/3/.
Auth method
API Token via HTTP Basic Auth. Credentials: user email address + API token. Store as JIRA_USER_EMAIL and JIRA_API_TOKEN in the credential store. OAuth 2.0 (3LO) is acceptable as an alternative if the orchestration platform supports it natively.
Required scopes (OAuth 2.0 3LO)
read:jira-user, write:jira-work, read:jira-work, manage:jira-project (required only if the automation creates or modifies issue types)
Webhook / trigger setup
No inbound Jira webhook is used. Jira is a downstream target only. Agent 1 calls POST /rest/api/3/issue to create. Agent 3 calls PUT /rest/api/3/issue/{issueIdOrKey} to update, POST /rest/api/3/issue/{issueIdOrKey}/comment for audit notes, and POST /rest/api/3/issue/{issueIdOrKey}/transitions to close.
Required configuration
Project key stored as JIRA_PROJECT_KEY. Issue type ID for 'IT Request' stored as JIRA_ISSUE_TYPE_ID. Transition ID for 'Done' or 'Resolved' stored as JIRA_DONE_TRANSITION_ID. All IDs must be retrieved from the target Jira project at setup time via GET /rest/api/3/project/{projectKey} and GET /rest/api/3/issue/{issueIdOrKey}/transitions; never hardcode numeric IDs.
Rate limits
Jira Cloud enforces a per-user rate limit of approximately 10 requests/second. At 60 requests/month, peak throughput is well within this ceiling. No throttling required. Implement exponential backoff on HTTP 429 responses regardless.
Constraints
The audit log comment must use Atlassian Document Format (ADF), not plain text, for API v3 comment bodies. Prepare a reusable ADF comment template stored in the credential store. Attachments are not required for this process.
Okta (REST API v1)
Used by Agent 2 for identity challenge (factor verification) and by Agent 3 for password resets and group/role assignment. Base URL: https://<your-okta-domain>.okta.com/api/v1/.
Auth method
SSWS API Token for server-side service account. Create a dedicated service account in Okta with minimum required admin privileges. Store the token as OKTA_API_TOKEN. OAuth 2.0 with a confidential service app (client_credentials flow) is the recommended path for new builds; store CLIENT_ID and CLIENT_SECRET accordingly.
Required scopes (OAuth 2.0 service app)
okta.users.read, okta.users.manage, okta.groups.read, okta.groups.manage, okta.factors.read, okta.factors.manage, okta.sessions.manage
Webhook / trigger setup
No inbound Okta webhook is used in this process. Okta is called by the orchestration layer. For identity challenge: POST /api/v1/users/{userId}/factors/{factorId}/verify. Poll for factor verification result via GET /api/v1/users/{userId}/factors/{factorId}/transactions/{transactionId} with a maximum of 10 polls at 6-second intervals before marking as timed-out.
Required configuration
Okta domain stored as OKTA_DOMAIN. Default factor type (e.g. token:software:totp or email) stored as OKTA_DEFAULT_FACTOR_TYPE. Target group IDs for each provisioned role stored as a key-value map OKTA_GROUP_MAP in the credential store (e.g. {"google-drive-finance": "00g1ab2cd3ef"}). Never hardcode group IDs in workflow logic.
Rate limits
Okta default rate limit for /api/v1/users is 600 requests/minute per org. Factor verify endpoint is 60 requests/minute. At 60 requests/month, neither limit is approached. No throttling required. The orchestration layer must still handle HTTP 429 with Retry-After header respect.
Constraints
Password reset via API (POST /api/v1/users/{userId}/lifecycle/reset_password) sends a reset email to the user's primary email. If a temporary password is required instead, use the expirePassword parameter. Okta MFA factor enrolment must exist before the challenge can be triggered; if a user has no enrolled factor, route immediately to IT escalation. Service account must not have Super Admin privileges; scope to User Admin and Group Admin only.
Google Workspace Admin SDK
Used by Agent 3 to add users to Google Groups and shared drives. API base URL: https://admin.googleapis.com/admin/directory/v1/. Drive API base URL: https://www.googleapis.com/drive/v3/.
Auth method
OAuth 2.0 with a Service Account and domain-wide delegation. The service account JSON key file must be stored as GOOGLE_SERVICE_ACCOUNT_JSON in the credential store. Impersonate a delegated admin account (GOOGLE_ADMIN_IMPERSONATE_EMAIL) with Directory API admin privileges. Never store the raw key in workflow code.
Required scopes
https://www.googleapis.com/auth/admin.directory.group, https://www.googleapis.com/auth/admin.directory.group.member, https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/drive
Webhook / trigger setup
Google Workspace is a downstream write target only. No incoming webhook. Agent 3 calls POST https://admin.googleapis.com/admin/directory/v1/groups/{groupKey}/members to add a member, and POST https://www.googleapis.com/drive/v3/files/{fileId}/permissions for shared drive access grants.
Required configuration
Group email addresses mapped to role names, stored as GOOGLE_GROUP_MAP in the credential store (e.g. {"finance-team": "finance@yourdomain.com"}). Admin impersonation email stored as GOOGLE_ADMIN_IMPERSONATE_EMAIL. Domain stored as GOOGLE_WORKSPACE_DOMAIN. All group keys must be verified to exist before the first production run.
Rate limits
Admin SDK Directory API: 3 queries/second per user; 1,500 queries/100 seconds per project. Drive API: 1,000 requests/100 seconds per user. At 60 requests/month, no throttling is required. Add a 500ms delay between sequential Google API calls in the same run as a precaution.
Constraints
Domain-wide delegation must be explicitly granted in the Google Workspace Admin console under Security, API controls. The service account client ID must be added with the exact scope strings listed above. Group membership propagation in Google Workspace can take up to 5 minutes to reflect in downstream apps; include this in user-facing confirmation messaging.
Microsoft Azure AD (Microsoft Graph API)
Used by Agent 2 for manager lookup only. The automation queries the Graph API to resolve the requester's direct manager for approval routing. Base URL: https://graph.microsoft.com/v1.0/.
Auth method
OAuth 2.0 Client Credentials flow (no user login). Register an App Registration in Azure AD. Store AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID in the credential store. Token endpoint: https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token.
Required scopes (application permissions)
User.Read.All, Directory.Read.All
Webhook / trigger setup
Azure AD is read-only in this process. No webhook. Agent 2 calls GET https://graph.microsoft.com/v1.0/users/{userId}/manager to resolve the manager's email address, which is then used to send the Slack approval message. The userId is resolved from the Slack user's email via GET /users/{email}.
Required configuration
AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID stored in the credential store. A fallback manager email stored as AZURE_FALLBACK_MANAGER_EMAIL for cases where a user has no manager set in the directory. The fallback triggers the IT escalation path with a flag noting the org-chart gap.
Rate limits
Microsoft Graph throttles at service level. User and directory read endpoints allow approximately 10,000 requests/10 minutes per app. At 60 requests/month, this limit is not a concern. Implement HTTP 429 and Retry-After handling as standard.
Constraints
Application permissions (not delegated) are required because the orchestration layer runs as a background service with no interactive login. Ensure the Azure AD App Registration has admin consent granted for the listed application permissions before first run. Users with no manager attribute set in Azure AD must be caught and routed to escalation, not failed silently.
Integration and API SpecPage 1 of 4
FS-DOC-05Technical
03Field mappings between tools
The following tables define the exact field mappings for each agent handoff. All source and destination field names are given in monospace notation as they appear in the respective API payloads.
Agent 1 handoff: Slack or web form to Jira (Request Intake Agent creates the Jira ticket)
Source tool
Source field
Destination tool
Destination field
Slack
`command`
Jira
`fields.summary`
Slack
`user_id`
Jira
`fields.reporter.id` (resolved via Slack users.info)
Slack
`user.email`
Jira
`fields.customfield_requester_email`
Slack / Form
`text` (parsed request type)
Jira
`fields.issuetype.id` (mapped from JIRA_ISSUE_TYPE_ID)
Slack / Form
`text` (parsed system name)
Jira
`fields.customfield_target_system`
Slack / Form
`request_type` (reset|new_access)
Jira
`fields.customfield_request_category`
Orchestration layer
`timestamp` (ISO 8601)
Jira
`fields.customfield_intake_timestamp`
Orchestration layer
`workflow_run_id`
Jira
`fields.customfield_automation_run_id`
Agent 2 handoff: Jira ticket to Okta (Verification and Approval Agent triggers identity challenge)
Source tool
Source field
Destination tool
Destination field
Jira
`fields.customfield_requester_email`
Okta
`login` (user lookup: GET /api/v1/users?filter=profile.email eq "...")
Okta (lookup result)
`id`
Okta
`userId` (path param for factor verify: POST /api/v1/users/{userId}/factors/{factorId}/verify)
Okta (lookup result)
`factors[0].id`
Okta
`factorId` (path param, defaulting to OKTA_DEFAULT_FACTOR_TYPE)
Jira
`fields.customfield_request_category`
Orchestration
`route` (reset -> Okta factor; new_access -> Azure AD manager lookup)
Agent 2 handoff: Azure AD to Slack (manager approval message routing)
Source tool
Source field
Destination tool
Destination field
Azure AD
`manager.mail`
Slack
`channel` (resolved to Slack user ID via users.lookupByEmail)
Azure AD
`displayName`
Slack
`blocks[].text` (requester name in approval message)
Jira
`fields.customfield_target_system`
Slack
`blocks[].text` (requested system in approval message)
Jira
`key`
Slack
`blocks[].value` (action_id payload for approve/deny callbacks)
Slack callback
`actions[0].value`
Orchestration
`approval_decision` (approved|denied)
Slack callback
`user.id`
Jira
`fields.customfield_approver_slack_id`
Agent 3 handoff: Approval decision to Okta and Google Workspace (Provisioning and Audit Agent)
Source tool
Source field
Destination tool
Destination field
Orchestration
`okta_user_id`
Okta
`userId` (path param for reset_password or addGroupMember)
Orchestration
`okta_group_id` (from OKTA_GROUP_MAP)
Okta
`groupId` (PUT /api/v1/groups/{groupId}/users/{userId})
Jira
`fields.customfield_target_system`
Google Workspace
`groupKey` (resolved from GOOGLE_GROUP_MAP)
Jira
`fields.customfield_requester_email`
Google Workspace
`memberKey` (POST /groups/{groupKey}/members body: `email`)
Orchestration
`approval_decision`
Jira
`fields.customfield_approval_outcome`
Orchestration
`provisioning_timestamp` (ISO 8601)
Jira
`fields.customfield_provisioned_at`
Okta (result)
`status`
Jira
`comment.body` (ADF audit note: action taken + outcome)
Google Workspace (result)
`kind`
Jira
`comment.body` (ADF audit note: group membership confirmed)
Orchestration
`workflow_run_id`
Jira
`comment.body` (ADF audit note: automation run reference)
Jira
`key`
Slack
`blocks[].text` (confirmation DM: ticket reference to requester)
Integration and API SpecPage 2 of 4
FS-DOC-05Technical
04Build stack and orchestration
Orchestration layout
Three discrete workflows, one per agent, within a single automation platform project. Workflows share a single encrypted credential store. Inter-workflow communication uses the shared credential store and event/webhook hand-off where supported, or a polling status check on the Jira ticket custom field as the state machine record.
Workflow 1: Request Intake Agent
Trigger: inbound webhook (Slack slash command payload or web form POST). Validates the Slack X-Slack-Signature header before any processing. Parses and classifies the request, creates the Jira ticket, and passes the ticket key and request type downstream via the shared run context.
Workflow 2: Verification and Approval Agent
Trigger: new Jira ticket created (polled every 60 seconds via Jira REST API GET /rest/api/3/search?jql=project=... AND status='Open' AND cf[automation_run_id] is not EMPTY, OR via Jira webhook on issue_created event if the plan supports outbound webhooks). Branches on request type. For password resets: triggers Okta factor verify and polls for result. For new access: queries Azure AD for manager, sends Slack approval message, and waits for callback webhook up to 2 hours with a reminder at 90 minutes.
Workflow 3: Provisioning and Audit Agent
Trigger: Slack interactive component callback (approval) or Okta factor verify success event (polled). Validates approval_decision value before any provisioning call. Executes Okta and Google Workspace API calls sequentially, sends Slack confirmation DM, and closes the Jira ticket.
Credential store
All secrets stored in the automation platform's native encrypted credential/environment variable store. No secret is written inline in any workflow node. Production and sandbox credential sets are named with a PROD_ and SANDBOX_ prefix respectively.
Signature validation
Slack: HMAC-SHA256 of raw request body using SLACK_SIGNING_SECRET, compared against X-Slack-Signature header. Reject any payload where timestamp in X-Slack-Request-Timestamp is older than 5 minutes. Jira webhooks (if used): validate via the secret token configured in the Jira webhook registration.
Credential store contents (all entries below are required before the first workflow run):
Credential store: all values marked *** must be supplied before first run. Never commit these values to source control.
# Slack
SLACK_BOT_TOKEN=xoxb-***
SLACK_SIGNING_SECRET=***
SLACK_ESCALATION_CHANNEL_ID=C0XXXXXXXXX
# Jira
JIRA_BASE_URL=https://<your-domain>.atlassian.net
JIRA_USER_EMAIL=automation-service@yourdomain.com
JIRA_API_TOKEN=***
JIRA_PROJECT_KEY=ITREQ
JIRA_ISSUE_TYPE_ID=10004
JIRA_DONE_TRANSITION_ID=31
# Okta
OKTA_DOMAIN=https://<your-okta-domain>.okta.com
OKTA_API_TOKEN=***
OKTA_DEFAULT_FACTOR_TYPE=token:software:totp
OKTA_GROUP_MAP={"google-drive-finance":"00g1ab2cd3ef","jira-dev-access":"00g4gh5ij6kl"}
# Google Workspace
GOOGLE_SERVICE_ACCOUNT_JSON=*** (base64-encoded JSON key)
GOOGLE_ADMIN_IMPERSONATE_EMAIL=admin-delegate@yourdomain.com
GOOGLE_WORKSPACE_DOMAIN=yourdomain.com
GOOGLE_GROUP_MAP={"finance-team":"finance@yourdomain.com","engineering":"eng@yourdomain.com"}
# Microsoft Azure AD
AZURE_CLIENT_ID=***
AZURE_CLIENT_SECRET=***
AZURE_TENANT_ID=***
AZURE_FALLBACK_MANAGER_EMAIL=it-escalation@yourdomain.com
# Orchestration
ENVIRONMENT=SANDBOX # Switch to PROD before go-liveThe ENVIRONMENT variable controls which credential prefix is active. All workflows must read this variable at the start of each run and select the correct credential set. A workflow that runs against PROD credentials while ENVIRONMENT=SANDBOX must throw a configuration error and halt.
Integration and API SpecPage 3 of 4
FS-DOC-05Technical
05Error handling and retry logic
Every integration point has a defined failure behaviour. Unhandled exceptions must never fail silently. Any error that does not match a defined scenario below must be caught by a global exception handler, logged with the workflow run ID and the raw error response, and posted to SLACK_ESCALATION_CHANNEL_ID with a summary before the workflow halts.
Integration
Scenario
Required behaviour
Slack (inbound)
Invalid or missing X-Slack-Signature on slash command payload
Reject immediately with HTTP 400. Log the raw headers. Do not process the payload. No retry.
Slack (inbound)
Slash command payload received but request_type cannot be classified
Reply to the user via chat.postMessage: 'We could not classify your request. Please use the web form or contact IT directly.' Update Jira ticket status to 'Needs Triage'. No retry.
Jira
POST /issue returns HTTP 400 (bad request, e.g. missing required field)
Log the full error body. Alert SLACK_ESCALATION_CHANNEL_ID. Do not retry. Requires manual fix of field mapping or Jira project config.
Jira
POST /issue or PUT /issue returns HTTP 429 or HTTP 503
Retry with exponential backoff: 5s, 15s, 45s (max 3 attempts). If all retries fail, log error with run ID and alert escalation channel. Do not drop the request.
Okta
User lookup returns no matching user (email not found in Okta)
Halt provisioning. Post alert to SLACK_ESCALATION_CHANNEL_ID with requester email. Update Jira ticket with comment: 'User not found in Okta. IT action required.' Mark ticket status as Escalated.
Okta
Factor verify endpoint returns no enrolled factor for user
Route to IT escalation immediately. Post to SLACK_ESCALATION_CHANNEL_ID: 'No MFA factor enrolled for [user]. Manual identity verification required.' Do not attempt password reset.
Okta
Factor verify polling reaches 10 attempts (60-second timeout) with no result
Mark identity challenge as timed out. Update Jira ticket. Notify requester via Slack: 'Your identity challenge timed out. Please try again or contact IT.' Close workflow run.
Okta
Password reset or group assignment returns HTTP 429
Retry with exponential backoff: 10s, 30s, 90s (max 3 attempts). If all fail, log and alert escalation channel. Do not mark access as granted.
Google Workspace
POST /groups/{groupKey}/members returns HTTP 409 (member already exists)
Treat as success. Log as 'already a member'. Continue workflow. Notify requester normally.
Google Workspace
Group key not found in GOOGLE_GROUP_MAP for the requested system
Halt Google Workspace step. Log unmapped system name. Alert SLACK_ESCALATION_CHANNEL_ID: 'No group mapping found for [system]. Manual provisioning required.' Update Jira ticket accordingly.
Azure AD
Manager lookup returns no manager attribute for the user
Use AZURE_FALLBACK_MANAGER_EMAIL. Add a flag in the Jira ticket comment: 'Manager not set in Azure AD directory. Approval sent to IT fallback. Org-chart review recommended.'
Slack (manager approval)
No approve or deny callback received within 2 hours (reminder fired at 90 min)
After 2 hours with no response, update Jira ticket status to 'Approval Timeout'. Alert SLACK_ESCALATION_CHANNEL_ID. Do not grant access. Notify requester: 'Your request is pending manager approval. IT has been notified.'
Global
Any unhandled exception in any workflow node
Catch via global error handler. Log: workflow run ID, agent name, node name, raw error, timestamp. Post summary to SLACK_ESCALATION_CHANNEL_ID. Halt workflow. Update Jira ticket if one exists. Never fail silently.
Retry backoff values above are minimums. If the orchestration platform enforces longer minimum delays (e.g. per-step execution limits), use the platform minimum where it exceeds the values listed here. All retry attempts must be logged individually with their attempt number and the HTTP response code received.
Integration and API SpecPage 4 of 4