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
  • Receive notifications when challenges complete

Setup

  1. Log in to the Challenge admin console at challenge.veraproof.io
  2. Navigate to Integrations → Slack Integrations
  3. Click Add Slack Integration
  4. Follow the OAuth flow to authorize the Challenge app in your Slack workspace
  5. Select the Slack workspace and channels where you want to use the integration
  6. Complete the authorization

The OAuth flow automatically configures all required permissions and URLs.

Option 2: Manual Installation via Manifest

If you prefer to install the Slack app manually using a manifest:

  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 automatically requested during the OAuth flow, or configured via the manifest.

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 message with a verification link
  4. The user clicks the link and completes identity verification via IdP SSO
  5. The administrator receives a notification when verification completes

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.

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 will automatically look up the corresponding Slack user IDs.

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.