API Documentation

Okta OAuth

Okta OAuth 2.0 Client Credentials (M2M) Setup

This guide details the two-part setup required in Okta to use the OAuth Machine-to-Machine (M2M) flow for securing your DecisionRules Solver API Key.

Part I: DecisionRules Resource API (Custom Authorization Server)

The Resource API is defined by an Okta Custom Authorization Server, which mints the JWT Access Tokens and validates the custom scope.

Step 1: Create the Custom Authorization Server

  1. Sign in to your Okta Admin Console.

  2. Navigate to Security > API.

  3. Select the Authorization Servers tab.

  4. Click Add Authorization Server.

  5. Name: Enter DecisionRules Solver API (or similar).

  6. Audience: Enter a unique identifier for this server, such as: https://decisionrules.io/solver-api

    • RECORD THIS VALUE. This is your Audience (AUD) and will be the Issuer (ISS) URI when requesting tokens.

  7. Click Save.

Step 2: Configure Claims

You must configure the Authorization Server to include a custom scope in the access token.

  1. Stay in the new DecisionRules Solver API Authorization Server and navigate to the Scopes tab.

  2. Click Add Scope.

  3. Configure the scope using your provided identifiers:

Field

Value

Name

decisionrules:orgid:12b057b4-865b-4545-81c4-8899d1da3537:spaceid:8ba6bac9-08a8-e648-8a2c-0b3992a9b4d6:solver

Display Name

DecisionRules Solver Access

Description

Allows machine clients to execute rules on the specified DecisionRules Organization and Space.

Default Scope

Leave unchecked.

Consent

Select No Consent Required.

  1. Click Create.

Key URLs from Authorization Server:

  • ISS (Issuer): Found under the Settings tab (e.g., https://{your-okta-domain}/oauth2/ausxxxxxxxxxx)

  • JWKS URL: Found under the Settings tab. DecisionRules requires this URL for token signature verification.

Part II: Client Application Setup

The Client Application is the machine or service that will authenticate and request the access token.

Step 1: Create the Service Application

  1. Navigate to Applications > Applications in the Okta Admin Console.

  2. Click Create App Integration.

  3. Sign-in method: Select API Services (or Service).

  4. Application Type: Select Client Credentials.

  5. Click Next.

  6. App integration name: Enter a name for your calling service (e.g., My ERP Client Service).

  7. Click Save.

  8. From the General tab, record the following critical values:

    • Client ID

    • Client Secret

Step 2: Grant Client Access via an Access Policy

You must configure the Custom Authorization Server to allow the new Client Application to access the custom scope.

  1. Navigate back to Security > API > Authorization Servers and select the DecisionRules Solver API server.

  2. Go to the Access Policies tab.

  3. If no policy exists, click Add New Policy.

    • Policy Name: E.g., M2M Client Credentials Policy.

    • Assign to: Set The following clients and add your My ERP Client Service application.

  4. Within the new policy, click Add Rule.

    • Rule Name: E.g., Client Credentials Grant.

    • If Grant Type is: Check Client Credentials.

    • If User is: Set The user assigned to the application.

    • THEN: Ensure the Access Token lifetime is set (e.g., 3600 seconds/1 hour).

    • Access Token with the following scopes: Include the full custom scope: decisionrules:orgid:12b057b4-865b-4545-81c4-8899d1da3537:spaceid:8ba6bac9-08a8-e648-8a2c-0b3992a9b4d6:solver.

  5. Click Create Rule.

Final Step: Requesting the Access Token

In the Okta Client Credentials flow, you explicitly request the custom scope name.

OAuth Parameter

Source Value

Token Endpoint URL

Authorization Server metadata (e.g., https://{your-okta-domain}/oauth2/ausxxxxxxxxxx/v1/token)

client_id

Client Application ID (from Part II, Step 1)

client_secret

Client Secret Value (from Part II, Step 2)

grant_type

client_credentials (Fixed value for M2M)

scope

The full, specific custom scope name (from Part I, Step 2) example: decisionrules:orgId:12b057b4-865b-4545-81c4-8899d1da3537:spaceId:8ba6bac9-08a8-e648-8a2c-0b3992a9b4d6:solver

Example Token Request:

AUTH_SERVER_URL="https://{your-okta-domain}/oauth2/ausxxxxxxxxxx"

curl --location --request POST "${AUTH_SERVER_URL}/v1/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "client_id=<Your Client ID>" \
--data-urlencode "client_secret=<Your Client Secret>" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "scope=decisionrules:orgid:12b057b4-865b-4545-81c4-8899d1da3537:spaceid:8ba6bac9-08a8-e648-8a2c-0b3992a9b4d6:solver"

Example Response:

// Some code
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJraWQiOiJvNzI0LTVhZXV5X2hnZTd1bE1mYXU2Nk1OZEFDeENNcV9GWGEyc002VD
  M0IiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULlEtOTc5eWVlMzJydUkteEFvOVpKZkFyU
  3VzMnAwNXVsNFh1R0xGcjNhd0UiLCJpc3MiOiJodHRwczovL3RyaWFsLTM2OTc5ODUub2t0YS5jb20vb2F
  1dGgyL2F1c3g1NnJrd3ZmOXVDVUNjNjk3IiwiYXVkIjoiaHR0cHM6Ly9hcGkubXljb21wYW55LmNvbS9yZ
  XNvdXJjZS1hcHAiLCJpYXQiOjE3NjM0NTk2NDAsImV4cCI6MTc2MzQ2MzI0MCwiY2lkIjoiMG9heDU2dDV
  zY0JSMG90U3A2OTciLCJzY3AiOlsiZGVjaXNpb25ydWxlczpvcmdJZDoxMmIwNTdiNC04NjViLTQ1NDUtO
  DFjNC04ODk5ZDFkYTM1Mzc6c3BhY2VJZDo4YmE2YmFjOS0wOGE4LWU2NDgtOGEyYy0wYjM5OTJhOWI0ZDY
  6c29sdmVyIl0sInN1YiI6IjBvYXg1NnQ1c2NCUjBvdFNwNjk3In0.wo6RIZWNvl_H0u5ghTgwPX126vB-n
  aZzWiNhAISbgwXkIEeR142eQ47Ew-8iCVw24O6lQWiZS0eSUWxHZLpHD_cM-NIbGw-xuGc__VgFDa-mqu
  gWMLqXiRgGSKzQfZNl6b77TXtf6PRIrUwMveIdNwHWjqCaTXGyiw-Veu9tPZjdsvYNKwVwq-BVP0VWaeY
  tblyFmao7A2TexYA0W3FOU7L180tbWHKSh2L4yURz59l3evOVbRktCvCi8NNqFNtYTh2c9Z6KCRkMzmi2
  O9RDjKlFd_fu5F1uokkueJw-lqmOk1kNTJUBIDgOzw9APgWJOd41L7zFOLx9NNUMVmC53g",
  "scope": "decisionrules:orgId:12b057b4-865b-4545-81c4-8899d1da3537:spaceId:8ba6bac9-08a8-e648-8a2c-0b3992a9b4d6:solver"
}

Example Decoded Access Token Data:

// Decoded headers
{
  "kid": "o724-5aeuy_hge7ulMfau66MNdACxCMq_FXa2sM6T34",
  "alg": "RS256"
}

// Decoded payload
{
  "ver": 1,
  "jti": "AT.Q-979yee32ruI-xAo9ZJfArSus2p05ul4XuGLFr3awE",
  "iss": "https://trial-3697985.okta.com/oauth2/ausx56rkwvf9uCUCc697",
  "aud": "https://api.mycompany.com/resource-app",
  "iat": 1763459640,
  "exp": 1763463240,
  "cid": "0oax56t5scBR0otSp697",
  "scp": [
    "decisionrules:orgId:12b057b4-865b-4545-81c4-8899d1da3537:spaceId:8ba6bac9-08a8-e648-8a2c-0b3992a9b4d6:solver"
  ],
  "sub": "0oax56t5scBR0otSp697"
}

The resulting Access Token will be a JWT containing the custom scope in the scp (scope) claim, which the DecisionRules Solver API will use to authorize the execution.

Last updated