Skip to content
Veraproof Veraproof Docs

Slack Integration

Slack Integration

Challenge integrates with Slack to enable identity verification via slash commands and programmatic API calls.

Overview

The Slack integration allows you to:

  • Use the /challenge slash command to request identity verification from any user
  • Create Slack-based challenges programmatically via webhook API
  • Use ChatOps challenge cards with configurable buttons and responder context capture
  • Receive challenge outcome updates directly in Slack

ChatOps Challenge Card

When a challenge is sent in Slack, the target user receives an interactive challenge card.

By default, the card includes:

  • A green button: Verify, it was me
  • A red button: Report incident, wasn’t me
  • An optional Additional context input field (configurable)

Challenge outcomes in Slack

Challenge messages are updated with terminal status so teams can see which requests were actioned:

  • verified
  • failed
  • expired
  • incident reported

For Slack-created challenges, outcome notifications are sent in Slack (instead of webhook callbacks).

Device fingerprint details

When a Slack-created challenge is successfully verified, device fingerprint details are sent to both:

  • the requester
  • the challenged user

This includes browser, OS, screen, renderer, timezone/language, location (if available), and public IP details when collected.

Setup

Install the Slack app from a manifest in your workspace, then enter the Slack credentials in the Challenge admin console to finish configuration.

  1. Log in to the Challenge admin console at challenge.veraproof.io
  2. Navigate to Integrations → Slack Integrations
  3. Click Add Slack Integration
  4. Copy your Tenant ID and Instance ID from the integration setup page
  5. Go to Slack API Apps and click Create New App → From manifest
  6. Select your workspace
  7. Paste the following manifest, replacing YOUR_TENANT_ID and YOUR_INSTANCE_ID with your actual values:
{
  "display_information": {
    "name": "Veraproof Challenge",
    "description": "Identity verification challenges via Slack",
    "background_color": "#1f2937",
    "long_description": "Veraproof Challenge enables secure identity verification requests through Slack. Use the /challenge command to request identity verification for team members. Visit https://veraproof.io/challenge for more information."
  },
  "features": {
    "bot_user": {
      "display_name": "Veraproof Challenge",
      "always_online": false
    },
    "slash_commands": [
      {
        "command": "/challenge",
        "description": "Request an identity verification challenge for a user",
        "usage_hint": "@username [reason]",
        "should_escape": false,
        "url": "https://challenge.veraproof.io/api/v1/slack/events/YOUR_TENANT_ID/YOUR_INSTANCE_ID"
      }
    ],
    "interactivity": {
      "is_enabled": true,
      "request_url": "https://challenge.veraproof.io/api/v1/slack/events/YOUR_TENANT_ID/YOUR_INSTANCE_ID"
    }
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "chat:write",
        "im:write",
        "users:read",
        "users:read.email",
        "commands"
      ]
    }
  },
  "settings": {
    "org_deploy_enabled": false,
    "socket_mode_enabled": false,
    "token_rotation_enabled": false
  },
  "_metadata": {
    "major_version": 2,
    "minor_version": 1
  }
}

Important: Before using the manifest, you must replace YOUR_TENANT_ID and YOUR_INSTANCE_ID in both URL fields with your actual tenant and instance IDs from the Challenge admin console. The URLs should look like:

  • https://challenge.veraproof.io/api/v1/slack/events/550e8400-e29b-41d4-a716-446655440000/660e8400-e29b-41d4-a716-446655440001
  1. Click Create to create the app
  2. On the OAuth & Permissions page, click Install to Workspace
  3. Copy the Bot User OAuth Token (starts with xoxb-)
  4. Navigate to Basic Information in the left sidebar
  5. Scroll down to App Credentials section and copy the Signing Secret
  6. Obtain your Workspace ID (aka Team ID) from your Slack workspace client URL. Open your Slack workspace in a browser (e.g., https://your-workspace.slack.com) and copy the workspace ID from the URL (it’s a unique string of characters starting with a T)
  7. Return to the Challenge admin console and paste the Bot User OAuth Token, Signing Secret, and Workspace ID to complete the integration

Required Slack Permissions

The Challenge Slack app requires the following permissions:

  • chat:write - To send challenge messages to users
  • im:write - To send direct messages to users
  • commands - To enable the /challenge slash command
  • users:read.email - To look up users by email address
  • users:read - To retrieve user profile information

These permissions are included in the manifest above.

Slack Integration Configuration Options

In Integrations → Slack Integrations, each workspace can configure ChatOps behavior:

  • Verify Button Label: Customize the green verification button text
  • Incident Button Enabled: Show or hide the red incident button
  • Incident Button Label: Customize red incident button text
  • Justification Field Mode: enabled or disabled
  • Justification Field Label: Customize the input field label
  • Justification Placeholder: Customize helper text in the input field
  • Justification Max Length: Limit input length

Justification behavior

  • When enabled, users can add context before clicking either button.
  • The verify button still redirects immediately.
  • Captured context is stored with challenge activity and is visible in admin activity views and API status responses.

Using the Slash Command

Basic Usage

In any Slack channel or direct message, type:

/challenge @username

This will create an identity verification challenge for the specified user.

With Context

You can include a context message explaining why the challenge is needed:

/challenge @username Access request for production database

Example Workflow

  1. A user requests access to a sensitive system via Slack
  2. An administrator types /challenge @username Access request for production database
  3. The target user receives a Slack challenge card with verification and incident options
  4. The user clicks Verify, it was me and completes identity verification via IdP SSO
  5. The original Slack message is updated with outcome status
  6. For verified Slack-origin challenges, requester and target receive device fingerprint details

Programmatic Slack Challenges

You can also create Slack-based challenges programmatically using the webhook API. This is useful for:

  • ITSM system integrations
  • Automated security workflows (SOAR playbooks)
  • Custom applications

See the Webhook Integration guide for details on creating Slack challenges via API.

Slack challenges created programmatically still use the Slack workspace ChatOps card configuration (button labels, incident toggle, and justification settings) for the selected integration instance.

Example: Create Slack Challenge via API

Terminal window
curl -X POST https://challenge.veraproof.io/api/v1/challenges \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_type": "slack",
    "requester_email": "admin@example.com",
    "target_user_email": "user@example.com",
    "context": "Automated security check"
  }'

Note: You can use email addresses instead of Slack user IDs—the system looks up the corresponding Slack user IDs. For webhook or MCP requests where no human requester is available, omit slack_user_id and requester_email; the Veraproof Challenge bot user is used as the requester in Slack messages.

Multiple Slack Workspaces

If your organization uses multiple Slack workspaces, you can configure multiple Slack integrations:

  1. Each integration is associated with a specific Slack workspace
  2. When creating challenges via API, you can specify which workspace to use with the slack_instance_id parameter
  3. If not specified, the system will use the first available Slack integration for your tenant

Troubleshooting

Slash Command Not Appearing

  • Ensure the Challenge Slack app is installed in your workspace
  • Check that the app has been added to the channels where you want to use it
  • Verify the app has the required permissions

Users Not Receiving Challenge Messages

  • Verify the target user is a member of the Slack workspace
  • Check that the Slack integration is properly configured
  • Ensure the user’s email address matches their Slack account email

API Errors

  • Verify your API key is correct
  • Check that at least one Slack integration is configured for your tenant
  • Ensure email addresses match Slack account emails

Support

For issues or questions, contact support@veraproof.io or refer to the Webhook Integration guide for API details.