Invoke a flow with an API endpoint

Secure with OAuth 2.0

Limited Early Access release

Use the following procedure to invoke the API endpoint for a flow using a secure OAuth 2.0 client credential exchange. This process requires a private JWT key.

Create an API service integration app

Creating an API service integration app is an ideal way to invoke a secured flow. The app's only purpose is to invoke the flow and return the output to the invoking request.

1. In the Admin Console, go to ApplicationsApplications.

2. Click Create App Integration.

3. Select API Services and click Next.

4. Provide an App integration name and select click Save to create your app integration.

   If you want to build your own API service, see Build your API service integration in the Okta developer documentation.

5. In the list of applications, open your new API service app.

6. On the General tab, edit the Client Credentials pane and select the Public key / Private key option.

7. Click Add key and in the dialog click Generate new key. Copy this private key value to your local system. Use this private key to sign the payload from your client when it calls the authorization server. The Okta authorization server uses the corresponding public key to validate the credentials and generate the access token. For more details on creating a service application, see Implement OAuth for Okta with a service app and Build a JWT for Client Authentication.

8. On the Okta API Scopes tab, click Grant for the okta.workflows.invoke.manage scope. Click Grant Access on the permissions dialog to confirm the action.

   If you built your own custom API service, add this scope as it is required for the invocation to work properly.

Configure your API endpoint settings

For existing API endpoint flows, you can skip the flow creation steps. Instead, click the Endpoint settings icon shown on the bottom of the API Endpoint event card in your flow.

1. Create a flow in your Workflows Console and click Add event.

2. From the Pick an app to start your flow dialog, select API Endpoint.

3. In the API endpoint settings dialog, select Secure with OAuth 2.0 as the security level.

4. Select which app integrations can trigger the flow when the Invoke URL receives a request:

   • Any: All app integrations in the org can trigger the flow if they have the appropriate scope.

   • Select from list: Use the dropdown menu to select specific app integrations that can trigger the flow. Each integration must have the appropriate scope.

     To filter the list, you can start typing the name of the integration inside the field. To remove any integrations from the list, click the 'X' beside the app name.

5. Click Close to confirm the changed endpoint settings.

Test your API endpoint flow

To test the OAuth protected endpoint, you need to use an OAuth client such as the Postman client.

In Postman, you can perform a GET or POST request to your Okta org's OAuth token endpoint at https://${yourOktaDomain}/oauth2/v1/token.

When the request is authenticated, the authorization server returns an access token that you can use to query the endpoint at the Invoke URL and invoke the flow.

Secure with client token

Use the following procedure to invoke a flow through a registered webhook.

For existing API endpoint flows, you can skip the flow creation steps. Instead, click the Endpoint settings icon shown on the bottom of the API Endpoint event card in your flow.

1. Create a flow in your Workflows Console and click Add event.

2. From the Pick an app to start your flow dialog, select API Endpoint.

3. In the API endpoint settings dialog, select Secure with client token as the security level.

4. When you select this option, it generates a Client token to identify the registered webhook. This unique client token is automatically added as the alias value in the Invoke URL and Resume URL fields.

5. Click copy to save the URL in the Invoke URL field.

6. Click Close to confirm the changed endpoint settings.

Test your API endpoint flow

To invoke the flow, perform a GET or POST request to the Invoke URL. Use the POST method if you need to send data in the body of the request.

If necessary, authenticate your request using one of the following methods.

• Pass the provided Client token using the clientToken query parameter. This is the default behavior.

• Pass the provided Client token as a value in the x-api-client-token header. This is the most secure option. However, don't use this together with the clientToken query parameter.

No security (public service)

Use the following procedure to invoke a flow as a public service.

For existing API endpoint flows, you can skip the flow creation steps. Instead, click the Endpoint settings icon shown on the bottom of the API Endpoint event card in your flow.

1. Create a flow in your Workflows Console and click Add event.

2. From the Pick an app to start your flow dialog, select API Endpoint.

3. In the API endpoint settings dialog, select None (public service) as the security level.

4. Copy the URL in the Invoke URL field.

5. Click Close to confirm the changed endpoint settings.

Test your API endpoint flow

To invoke the flow, perform a GET or POST request to the Invoke URL. Use the POST method if you need to send data in the body of the request.

At this security level, you don't need to pass along any authentication options in the request to invoke a flow.