Creating your own approval application

This topic describes how to create your own approval application, which serves as an intermediary between LaunchDarkly approvals and your workflow management application. This is a required step in building a custom approvals integration.

Overview

This topic describes how to create your own approval application, which serves as an intermediary between LaunchDarkly approvals and your workflow management application. This is the first step required in building a custom approvals integration. Only customers with complex workflow management or approval systems in third-party applications that LaunchDarkly does not integrate with directly are likely to need a custom approvals integration.

Create your own approval application

To use custom approvals, you must create and host your own approval application. This might be a standalone application, or it might be a middleware application that you deploy between LaunchDarkly and your existing third-party workflow management system, such as ServiceNow. If you are working with a third-party workflow management system, then your application should transform outgoing LaunchDarkly requests related to approval flows and forward them to the approval service of your choice.

You can find the configuration for the full integration and associated requests in our public integration frameworks repository.

Authentication

LaunchDarkly will send requests to your application using the request header "Authorization": "Bearer <API_KEY>". LaunchDarkly will save an encrypted version of this key and use it to authenticate all outgoing requests from our service to yours.

You specify both the API_KEY and the BASE_URL that LaunchDarkly should use when you define the integration configuration for custom approvals integration. LaunchDarkly saves this information as part of the integration configuration, and uses it only to construct outgoing requests from LaunchDarkly to your custom application.

Requests from Launch

Darkly to your applicationLaunchDarkly will make the following requests to your application:

• creationRequest: LaunchDarkly sends this upon approval request creation. The input from the additionalApprovalFormVariables defined on your custom approvals integration configuration will be merged into the body of this request.
• statusRequest: LaunchDarkly sends this every five minutes, or whenever the approval request page in LaunchDarkly is refreshed.
• postApplyRequest: LaunchDarkly sends this after a LaunchDarkly approval request has been applied.
• deletionRequest: LaunchDarkly sends this whenever a LaunchDarkly approval request is deleted.
• memberListRequest: (optional) LaunchDarkly sends this upon setup, and every four hours thereafter, to associate LaunchDarkly member resources with corresponding external user objects. The custom-approvals integration manifest defines generic versions of these requests. The following sections describe the requests in more detail.

creation

Request and required responseHere’s the specification for the creationRequest that LaunchDarkly sends:

| Request element

Description

| --- | | Method

| POST | | URL

| <BASE_URL>/api/approvals
Specify the BASE_URL that LaunchDarkly should use in the custom approvals integration configuration. | | Headers

| { "Content-Type": "application/json", "Authorization": "Bearer <API_KEY>"}

Specify the API_KEY that LaunchDarkly should use in the custom approvals integration configuration. | | Request body (sample)

| maxLines=0 { "_site": { "href":"https://app.launchdarkly.com/default/sample-env/features/sample-flag/approvals/66a8e20c0754610fae1fcf5d" }, "_id":"66a8e20c0754610fae1fcf5d", "details":"Created approval request: this is an example comment Requested change is: Turn on the flag", "project": { "name":"Default Project", "key":"default", "tags":["sample", "sample-2"] }, "environment": { "name":"Sample Environment", "key":"sample-environment", "tags":["sample"] }, "flag": { "name":"Sample Flag", "key":"sample-flag", "tags":["sample"] }, "shortDescription":"Jane Doe requested approval for changes to the flag Sample Flag in 'Sample Environment'", "timestamp": "1746196607127", "comment": "this is an example comment", "approvalFormVariables": { "yourCustomVariable1": "blue", "yourCustomVariable2": "green" } }

|LaunchDarkly expects the following response from your application:

| Response element

Description

| --- | | HTTP Code

| 2xx | | Body

| { "_id": <APPROVAL_ID>, // as taken from the request from LD "status": { "value": "approved", "display": "Approved" } }

LaunchDarkly considers status values of approved or declined as approved or declined requests. The display can be any string and is displayed in the LaunchDarkly user interface. |

status

Request and required responseHere’s the specification for the statusRequest that LaunchDarkly sends:

| Request element

Description

| --- | | Method

| GET | | URL

| <BASE_URL>/api/approvals/<APPROVAL_ID>/status

Specify the BASE_URL that LaunchDarkly should use in the custom approvals integration configuration. The APPROVAL_ID will be one of the approvalId values that LaunchDarkly has already sent in a creationRequest. | | Headers

| { "Authorization": "Bearer <API_KEY>"}

Specify the API_KEY that LaunchDarkly should use in the custom approvals integration configuration. | | Request body (sample)

| The request asks for the status of the APPROVAL_ID. The request body is empty. |

LaunchDarkly expects the following response from your application:

| Response element

Description

| --- | | HTTP Code

| 2xx | | Body

| { "status": { "value": "pending", "display": "Pending review" } }

LaunchDarkly considers status values of approved or declined as approved or declined requests. The display can be any string and is displayed in the LaunchDarkly user interface. |The display string that LaunchDarkly receives when loading the approvals request page displays at the bottom of the right-hand sidebar:

post

ApplyRequest and required responseHere’s the specification for the postApplyRequest that LaunchDarkly will send:

| Request element

Description

| --- | | Method

| POST | | URL

| <BASE_URL>/api/approvals/<APPROVAL_ID>/apply

Specify the BASE_URL that LaunchDarkly should use in the custom approvals integration configuration. The APPROVAL_ID will be one of the approvalId values that LaunchDarkly has already sent in a creationRequest. | | Headers

| { "Content-Type": "application/json", "Authorization": "Bearer <API_KEY>"}

Specify the API_KEY that LaunchDarkly should use in the custom approvals integration configuration. | | Request body (sample)

| The request indicates that APPROVAL_ID has been applied in LaunchDarkly. The request body is empty. |

LaunchDarkly expects the following response from your application:

| Response element

Description

| --- | | HTTP Code

| 2xx | | Body

| { "status": { "value": "declined", "display": "declined" } }

LaunchDarkly considers status values of approved or declined as approved or declined requests. The display can be any string and is displayed in the LaunchDarkly user interface. |

deletion

Request and required responseHere’s the specification for the deletionRequest that LaunchDarkly will send:

| Request element

Description

| --- | | Method

| POST | | URL

| <BASE_URL>/api/approvals/<APPROVAL_ID>/cancel

Specify the BASE_URL that LaunchDarkly should use in the custom approvals integration configuration. The APPROVAL_ID will be one of the approvalId values that LaunchDarkly has already sent in a creationRequest. | | Headers

| { "Content-Type": "application/json", "Authorization": "Bearer <API_KEY>"}

Specify the API_KEY that LaunchDarkly should use in the custom approvals integration configuration. | | Request body (sample)

| The request indicates that APPROVAL_ID has been deleted in LaunchDarkly. The request body is empty. |

LaunchDarkly expects the following response from your application:

| Response element

Description

| --- | | HTTP Code

| 2xx | | Body

| { "status": { "value": "cancelled", "display": "Cancelled" } }

LaunchDarkly considers status values of approved or declined as approved or declined requests. The display can be any string and is displayed in the LaunchDarkly user interface. |

member

ListRequest and optional responseHere’s the specification for the memberListRequest that LaunchDarkly will send:

| Request element

Description

| --- | | Method

| GET | | URL

| <BASE_URL>/api/members | | Headers

| { "Authorization": "Bearer <API_KEY>"}

Specify the API_KEY that LaunchDarkly should use in the custom approvals integration configuration. | | Request body (sample)

| The request asks for LaunchDarkly members. The request body is empty. |

Responding to this request is optional. If implemented, LaunchDarkly expects the following response from your application:

| Response element

Description

| --- | | HTTP Code

| 2xx | | Body

| { "members": [ { "name": "Jane Doe", "email": "[e-mail]" }, { "name": "Sandy Smith", "email": "[e-mail]" }, ... etc ] }

|

Review your approval request externally

In addition to facilitating the synchronization of your external approval request and your LaunchDarkly approval request, your application should also provide a route to review your external approval request externally, either by providing or by forwarding the user to a UI for providing reviews. LaunchDarkly assumes that this will be hosted at <BASE_URL>/approvals?approvalID=<APPROVAL_ID> and will provide a “Review in [your app name]” button on the “Review approval request” page linking to this external URL:

It may also display an “Apply changes” button after it is reviewed or if reviews are not required on your environment.