Making decision requests to Authorize gateway instances

Use the POST localhost:<port>/api/authorize operation to execute a decision request against a gateway instance.

You can make decision requests to an Authorize gateway instance to determine whether a user or system is permitted to perform a specific action. Requests are evaluated in your organization’s infrastructure, while policies are centrally managed in PingOne. This approach combines the performance of self-managed evaluation and enforcement with the convenience of centralized administration.

Gateway instances can handle the following types of decision requests:

Individual request: A single decision request including a set of parameters and optional PingOne user context.
Bulk request: An array of individual decision requests evaluated with a single API call. Bulk requests reduce latency and network overhead when you need to evaluate several access scenarios at once.

Before you execute decision requests against gateway instances in your organization’s infrastructure, make sure you’ve completed steps 1 - 5 in Setting up an Authorize gateway.

Authentication

You can enforce client authentication on the /api/authorize endpoint by configuring a shared secret. Learn more in Authentication for Authorize gateway endpoints.

Individual request body

The request body requires the parameters property.

The userContext property is required when your authorization policies include built-in PingOne User attributes. Learn more in Built-in attributes.

Parameters consist of an attribute name and value separated by a colon. For example:

{
  "parameters": {
    "Amount": "990",
    "Account": "Basic Checking",
    "Payment.consentId": "{{consentID}}"
  },
  "userContext": {
    "user": {
      "id": "{{userID}}"
    }
  }
}

Example individual request

The following request checks whether a user with ID 12356bca-0e34-4c02-8b19-51349ddd4ed5 is permitted to make a payment of 990 USD:

curl --location 'http://localhost:8080/api/authorize' \
  --header 'Authorization: Bearer example-secret' \
  --header 'Content-Type: application/json' \
  --data '{
    "parameters": {
      "Amount": 990
    },
    "userContext": {
      "user": {
        "id": "12356bca-0e34-4c02-8b19-51349ddd4ed5"
      }
    }
  }'

Example individual response

The gateway instance evaluates the request and returns a PERMIT decision, meaning the payment is allowed:

{
   "id": "13234d13-7cc5-4394-a1a4-c685cbff4a5d",
   "authorizationVersion": {
       "id": "2027cfbe-4fcc-46f8-9c2f-d1f34983a43f"
    },
   "timestamp": "2025-07-25T23:09:11.439455948Z",
   "elapsedMicroseconds": 409,
   "decision": "PERMIT",
   "authorized": true,
   "statements": [],
   "status": {
       "code": "OKAY",
       "messages": [],
       "errors": []
   }
}

Bulk request body

A bulk request body contains two main parts:

Top-level properties: parameters and userContext, which apply to all decision requests. These properties are optional.
decisionRequests: An array of individual decision requests, each with its own parameters and userContext. This property is required.

There’s no limit on how many individual requests you can include in the decisionRequests array.

If the same property is defined at both levels, the value in the individual request overrides the top-level value.

The userContext property is required when your authorization policies include built-in PingOne User attributes. Learn more in Built-in attributes.

{
  "parameters": {
    "resource.type": "payment",
    "resource.currency": "USD"
  },
  "userContext": {
    "user": {
      "id": "{{userID}}"
    }
  },
  "decisionRequests": [
    {
      "parameters": {
      "requestId": "payment-001",
      "resource.amount": 120,
      "accountBalance": 500
      }
    },
    {
      "parameters": {
      "requestId": "payment-002",
      "resource.amount": 2000,
      "accountBalance": 1000
      }
    }
  ]
}

Example bulk request

This request evaluates two payment authorization scenarios with a single API call: one for 120 USD with a balance of 500 USD, and another for 2000 USD with a balance of 1000 USD:

curl --location --request POST 'http://localhost:8080/api/authorize' \
  --header 'Authorization: Bearer example-secret' \
  --header 'Content-Type: application/vnd.pingidentity.decisionengine.authorize.bulk+json' \
  --data-raw '{
    "parameters": {
      "resource.type": "payment",
      "resource.currency": "USD"
    },
    "userContext": {
      "user": {
        "id": "12356bca-0e34-4c02-8b19-51349ddd4ed5"
      }
    },
    "decisionRequests": [
      {
        "parameters": {
          "requestId": "payment-001",
          "resource.amount": 120,
          "accountBalance": 500
        }
      },
      {
        "parameters": {
          "requestId": "payment-002",
          "resource.amount": 2000,
          "accountBalance": 1000
        }
      }
    ]
  }'

Example bulk response

The first request (payment-001) is permitted because the balance is sufficient, while the second request (payment-002) is denied because of insufficient funds:

{
  "summary": {
    "requested": 2,
    "errors": 0,
    "successful": 2
  },
  "correlationId": "a1b2c3d4-e5f6-7890-1234-567890fedcba",
  "authorizationVersion": {
    "id": "v2024-09-26-policy"
  },
  "timestamp": "2025-09-26T16:03:09.123456Z",
  "responses": [
    {
      "id": "payment-001",
      "elapsedMicroseconds": 150000,
      "decision": "PERMIT",
      "statements": [
        {
          "name": "Transaction Approved",
          "code": "TXN-APPROVED",
          "payload": "{\"resource.type\": \"payment\", \"resource.currency\": \"USD\", \"resource.amount\": 120.00, \"accountBalance\": 500.00}"
        }
      ],
      "status": {
        "code": "OKAY",
        "messages": [
          "Balance check passed: $500.00 > $120.00"
        ],
        "errors": []
      }
    },
    {
      "id": "payment-002",
      "elapsedMicroseconds": 180000,
      "decision": "DENY",
      "statements": [
        {
          "name": "Insufficient Funds",
          "code": "INSUF-FUNDS",
          "payload": "{\"resource.type\": \"payment\", \"resource.currency\": \"USD\", \"resource.amount\": 2000.00, \"accountBalance\": 1000.00}"
        }
      ],
      "status": {
        "code": "OKAY",
        "messages": [
          "Balance check failed: $1000.00 < $2000.00"
        ],
        "errors": []
      }
    }
  ]
}