Skip to content

Integrating SailPoint with StackHawk

StackHawk is a cloud-based dynamic application security testing (DAST) platform for organizations that need to find and fix security bugs in their applications and APIs before they reach production. It combines the HawkScan scanner, CI/CD-integrated scanning, findings triage, scan policy management, and organization/team-based access control into a single platform, providing visibility into scan results and findings across every application a team owns. This document provides instructions to configure a new direct connection to a StackHawk source. For a reference to the terminology specific to SailPoint products, refer to Source and Connector Definitions.

Note

To view the latest features, enhancements, and fixes for all SaaS connectors, refer to the SaaS Release Notes page.

Supported Features

The StackHawk connector supports the following:

Account Management

  • Aggregate Members

Entitlement Management

  • Aggregate Role

Note

User role is captured as part of account aggregation (embedded within the member record via the role attribute), so a separate entitlement aggregation is not required.

Important

Quick Compliance connectors have the following manual aggregation limits within a 24-hour period:

  • Organization Admins: Limited to 3 manual account or entitlement aggregations per day per source. This limit is cumulative across all admins in the organization.
  • Regular Users: Limited to 1 manual account or entitlement aggregation per day per source.

These limits ensure that individual compliance statuses are kept up to date while maintaining continuous compliance monitoring. If you need to run additional aggregations beyond these limits, contact SailPoint Support.

Prerequisites

Before you configure the StackHawk connector, ensure the following requirements are met:

  1. Confirm your StackHawk Organization belongs to a plan with API Access enabled. If it is not enabled, contact StackHawk support.
  2. Sign in to StackHawk with a user account that has the permission to read your organization's members (see Required Permissions).
  3. Go to Settings > API Key.
  4. Select Create New API Key, give the key a descriptive name, and confirm creation.
  5. Copy the generated API Key immediately and store it securely. StackHawk displays the full key only once. If the key is lost, create a replacement from the same page.
  6. StackHawk also documents an in-product location under Settings > Organization Details, but that is a tab not visible in free trial. Retrieve your Organization Id using the StackHawk API Docs Try It! flow in the next section.
  7. Copy and securely store the following details, which are required during connector configuration:
    • Base URL - https://api.stackhawk.com
    • API Token (the StackHawk API Key, sent in the X-ApiKey header)
    • Organization Id (the UUID of your StackHawk Organization)

Note

  • A StackHawk API Key is personal. It is issued to and owned by a specific user, and requests made with it are associated with that calling user. API resources are only accessible to the applications and organizations that user belongs to and is permissioned to access. Offboarding or removing that user will break any integration using their key, so create the connector's key under a dedicated service/role-based user account where possible.
  • StackHawk Service Keys are organization-owned rather than user-owned, but they are created with the Scan Only role, which cannot manage or read users. Service Keys are therefore not usable for this connector; a personal API Key owned by a suitably permissioned user is required.
  • The API Key is exchanged for an access token. Access tokens are RFC-7519 JWTs and expire after 30 minutes. The connector performs this exchange through its Custom Authentication endpoint on each session.

For more detailed information on obtaining an API Key and access token, refer to the official StackHawk documentation: StackHawk API documentation and API authentication login.

Required Permissions

Typical Roles That Can Generate Tokens

StackHawk's organization roles are Owner, Admin, Team Admin, Member, and View Only. The API Key is created by an individual user from their own Settings > API Keys page, and the key inherits that user's role permissions, so what matters is not who can create a key, but whether that user's role grants the permissions the connector's endpoints require.

The connector's endpoints require the following StackHawk API permissions:

  • read:member

  • read:profile

  • View Only - Recommended minimum. View Only is StackHawk's read-only auditor role: it can view organization members, teams, and role assignments across all teams, and can create and manage API keys, with those keys inheriting the read-only View Only permission set. This matches the connector's read-only behaviour with least privilege.

  • Owner/Admin - Both have broad organization-wide access and can read organization members. Use these only if the View Only role is unavailable on your plan, as they grant far more access than the connector needs.
  • Team Admin/Member - Not recommended. These roles are team-scoped and cannot access organization settings; StackHawk does not publish a role-to-permission matrix confirming whether they hold read:member for the whole organization.

Retrieving the Organization ID Using the StackHawk API Docs

Use the Try It! panel in the StackHawk API Docs. This is the recommended way to obtain the Organization Id, because it does not depend on a Settings UI tab being present:

  1. Open the Login with API Key reference page.
  2. In the right-hand request panel, enter your StackHawk API Key in the X-ApiKey header field.
  3. Select Try It!. A 200 response is returned containing a single field, token - this is your bearer access token. Copy its value.
  4. Open the Get the current user reference page.
  5. Supply the copied token as the bearer credential for the request (header Authorization: Bearer <token>), then select Try It!.
  6. In the 200 response, read the value at user.external.organizations[].organization.id - this is the UUID identifier of your StackHawk Organization. The organization name is alongside it at user.external.organizations[].organization.name, which is useful when you belong to more than one organization.
  7. Paste that UUID into the connector's Organization Id field.

Note

The token returned by /api/v1/auth/login expires after 30 minutes. If a Try It! request returns 401 Unauthorized, repeat the login step to obtain a fresh token. StackHawk recommends using /login only when starting a new access session and /refresh to extend an existing one.

Note

The linked document is not maintained by SailPoint and is subject to change without notice.