Invoke a flow with an API endpoint using OAuth 2.0

Early Access release. See Enable self-service features.

Secure your API endpoint flow using OAuth 2.0 protocols for authorization of scoped access tokens.

After you invoke a flow, it sends the flow output as a response object.

Use the following procedure to invoke the API endpoint for a flow using a secure OAuth 2.0 client credential exchange. This process requires the use of a private JSON Web Token (JWT).

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.

9. 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. Add the appropriate scopes to any app integration that needs to call the API.

Create your flow

For existing API endpoint flows, you can skip these two 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.

Configure your API endpoint settings

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

2. 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.

3. 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.

See Invoke and Test an OAuth 2.0 Secured API Endpoint for a detailed explanation of the testing process for OAuth 2.0 flows.

Related topics

Function: API Endpoint

Flow aliases

Flow client token