JSON request body support for OAuth token URL

Overview

Simpplr now supports sending OAuth 2.0 token requests using a JSON request body (application/json) instead of the default form-encoded format (application/x-www-form-urlencoded).

This is useful for third-party APIs that require token requests to be sent as JSON with specific fields. The feature is available in Custom Apps and can be enabled during OAuth configuration.

Who can use this

• App Managers

• Administrators configuring Custom Apps

When to use this

Enable a JSON request body only if the third-party provider explicitly requires:

• Content-Type: application/json

• A structured JSON payload for token requests

If your provider supports or expects the default form-encoded format, this setting should remain disabled.

How it works

By default, Simpplr sends OAuth token requests as form-encoded. This behavior remains unchanged unless explicitly configured.

When Enable custom JSON request body is selected:

• A JSON editor becomes available in the Token URL section

• The request body is sent as JSON

• Content-Type is automatically set to application/json

• The default form-encoded behavior is overridden

If the option is not enabled, Simpplr continues using the standard form-encoded request format.

Key behavior

• JSON configuration is opt-in and applies only to the selected app

• The system enforces the correct Content-Type automatically

• Custom headers can still be added, but conflicting Content-Type values are ignored

• Existing integrations are not affected

Validation rules

The JSON body must meet the following conditions:

• It cannot be empty or contain only whitespace

• It must be valid JSON syntax

• Invalid or malformed JSON blocks saving

If validation fails, the configuration cannot be completed until the issue is resolved.

Example JSON payloads

Client credentials flow

{
  "clientId": "{{clientId}}",
  "clientSecret": "{{clientSecret}}",
  "grantType": "client_credentials",
  "scope": "all"
}

Authorization code with PKCE

{
  "grant_type": "authorization_code",
  "client_id": "{{clientId}}",
  "code": "{{authorizationCode}}",
  "redirect_uri": "{{redirectUri}}",
  "code_verifier": "{{codeVerifier}}"
}

Use the exact field names and structure required by your provider.

Configure JSON request body

Before you begin

• Ensure you have permissions to manage Custom Apps

• Confirm your provider requires a JSON token request

• Keep the required payload format ready

Steps

1. Go to Manage → Application settings → Integrations → Custom apps

2. Create a new app or edit an existing one

3. Set:

   • Auth type to OAuth 2.0

   • Select the required OAuth flow

4. In the Token URL section, enable custom JSON request body

5. Enter a valid JSON payload in the editor

6. (Optional) Add any required custom headers

7. Save the configuration

After saving, reopen the app to confirm the setting and JSON body are retained.

Behavior summary

Permissions and compatibility

• This feature applies only to Custom Apps using OAuth 2.0

• Existing apps continue to work without changes

• Each app can be configured independently

Troubleshooting

JSON option not visible

• Ensure OAuth 2.0 is selected as the authentication type

• Confirm the feature is available in your environment

Invalid JSON error

• Check syntax (use double quotes, remove trailing commas)

• Ensure the structure matches provider requirements

Token request fails

• Verify field names and required parameters

• Check Token URL and environment (production vs sandbox)

• Review the provider’s error response and adjust the payload