Generic HTTP Connector

The Generic HTTP Connector enables integration between Descope and any third-party HTTP API. Use it to pull data into Descope flows (e.g., user information) or push data to external services.

Connector Settings

Once you've configured all of these settings, you can test the connector in the connector configuration page.

Authentication Methods

The Generic HTTP Connector supports several authentication mechanisms. You can choose the one that matches the requirements of the third-party API you are connecting to:

OAuth 2.0 (Client Credentials Flow)

When using OAuth 2.0, Descope will handle token retrieval and injection into requests automatically. You must provide the following:

• Client ID
• Client Secret
• Token Endpoint URL
• Scopes (optional; space-separated string)
• Credential Placement: Choose whether to send the credentials:
  • In the request body
  • In the Authorization header using HTTP Basic (default)

Descope will fetch and cache the access token using the client credentials flow and include it in the Authorization header for subsequent requests.

Testing the Connector

Use the Descope Console to test your HTTP connector and verify the integration. For example, you can pull user details from an external API and review them in the test panel.

Handling HTTP Status Codes

You can handle different HTTP responses in your flow using conditionals based on the status code.

Step 1: Enable Custom Error Handling

Configure the connector action to use Custom error handling for the Generic HTTP Error event. Doing this will result in the flow redirecting to a new path in the flow if the response code is not 200.

You can also set Connector Execution error handling to Custom to handle errors with the connector itself.

Step 2: Add Conditional Logic

Use the key connectors.<Context Key>.statusCode to access the response code in flow conditions.

Example use cases:

• 404 → Show "User Not Found" screen.
• 429 → Return to login screen.
• Other errors → Restart the flow.

For a complete list of response codes, you can visit the HTTP Status Codes page.

Step 3: Build Flow Logic

Connect conditions and screens to build the complete flow logic. This is an example of a flow that will restart the process if a 429 rate limit error occurs, but will show a "User Not Found" screen if a 404 error occurs.

Accessing HTTP Response Headers

Enable the Include response headers in Context option in the connector settings to access headers in your flow (context.headers).

For example, you can:

• Extract custom headers.
• Use them in a Custom Claims action.
• Add the values to the JWT.

{
  "customHeader": "My header value",
  ...
}

HMAC Signature Customization

You can customize the HMAC signature template used to sign requests sent from Descope.

Configure Signature Template

In the connector settings, set a x-descope-signature-template header with a comma-separated list of elements to sign:

Example template: METHOD,URI,HEADER_x-descope-timestamp,BODY

Descope will compute the HMAC and send it in the x-descope-webhook-s256 header.

Example Headers Sent

{
  "x-descope-webhook-s256": "xxxxx",
  "x-descope-timestamp": "1717787565548",
  "x-descope-signature-template": "METHOD,URI,HEADER_x-descope-timestamp,BODY"
}

Validating the Signature

Use the following example to validate the HMAC signature in your backend:

import crypto from "crypto";
 
function verifyHmacSignature(payload, secret, sentHmac) {
  const hmac = crypto.createHmac("sha256", secret).update(payload).digest("base64");
  return sentHmac === hmac;
}
 
export async function validateHMAC(req) {
  const secret = "ConfiguredSigningSecret";
  const template = req.headers["x-descope-signature-template"];
  let signature = template.replace("METHOD", req.method).replace("URI", req.url);
 
  if (template.includes("BODY")) {
    signature = signature.replace("BODY", JSON.stringify(req.body || {}));
  }
 
  const headerMatches = template.match(/HEADER_([a-zA-Z0-9-_?~]+)/g) || [];
  headerMatches.forEach(h => {
    const name = h.replace("HEADER_", "");
    signature = signature.replace(h, req.headers[name] || "");
  });
 
  const sentHmac = req.headers["x-descope-webhook-s256"];
  return verifyHmacSignature(signature, secret, sentHmac);
}

Dynamic Values in Headers

You can inject dynamic values (e.g., form fields or flow inputs) into headers. These can also be dynamic values generated from a connector or scriptlet.

Using Values from Other Connectors

A common use case is chaining connectors together, where one connector's output becomes another connector's input.

You can use the output of a connector and include it in the request body of your generic HTTP connector in the flow itself. However, if the output of the one connector must be included in the headers of your generic HTTP connector, you can do that as well. Here's an example:

1. First, use a Database Connector to fetch a user's profile
2. Then, use the Generic HTTP connector to call an external API, passing the user's data in headers

Example flow:

{
  "x-user-id": "{{connectors.dbResult.user.id}}",
  "x-user-role": "{{connectors.dbResult.user.role}}",
  "x-tenant-id": "{{connectors.dbResult.tenant.id}}"
}

This can also be used if there a dynamic token that needs to be included in the headers of the generic HTTP connector for authentication, that doesn't rely on OAuth 2.0 Client Credentials flow.

Example

Header configuration in the connector:

{
  "x-descope-form-email": "{{form.email}}",
  "x-descope-testid": "{{form.testID}}"
}

Example of received headers:

{
  "x-descope-form-email": "chris+200@descope.com",
  "x-descope-testid": "12345678"
}

Static IP Addresses

When using the Generic HTTP Connector, you may want to restrict access to your third-party API by IP address. Descope provides the option to route all requests from the connector through a set of static IPs.

In the connector configuration screen, you can enable Use Static IPs. When this option is selected:

• Descope will route all outgoing requests through a predefined set of IP addresses.
• These IPs are displayed in the UI for you to copy and whitelist on your API gateway, firewall, or server.