Bulk merge-patch API mappings.

curl --request PATCH \
  --url https://{tenant}/api/clientidps/{id}/mappings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "4c1c0d8fc885401053ddac4e39ef676b": {
    "scope_to_policy": {
      "read": "665d51505715ec2d76022c87",
      "write": null
    }
  }
}
'

import requests

url = "https://{tenant}/api/clientidps/{id}/mappings"

payload = { "4c1c0d8fc885401053ddac4e39ef676b": { "scope_to_policy": {
            "read": "665d51505715ec2d76022c87",
            "write": None
        } } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    '4c1c0d8fc885401053ddac4e39ef676b': {scope_to_policy: {read: '665d51505715ec2d76022c87', write: null}}
  })
};

fetch('https://{tenant}/api/clientidps/{id}/mappings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{tenant}/api/clientidps/{id}/mappings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    '4c1c0d8fc885401053ddac4e39ef676b' => [
        'scope_to_policy' => [
                'read' => '665d51505715ec2d76022c87',
                'write' => null
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{tenant}/api/clientidps/{id}/mappings"

	payload := strings.NewReader("{\n  \"4c1c0d8fc885401053ddac4e39ef676b\": {\n    \"scope_to_policy\": {\n      \"read\": \"665d51505715ec2d76022c87\",\n      \"write\": null\n    }\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://{tenant}/api/clientidps/{id}/mappings")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"4c1c0d8fc885401053ddac4e39ef676b\": {\n    \"scope_to_policy\": {\n      \"read\": \"665d51505715ec2d76022c87\",\n      \"write\": null\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{tenant}/api/clientidps/{id}/mappings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"4c1c0d8fc885401053ddac4e39ef676b\": {\n    \"scope_to_policy\": {\n      \"read\": \"665d51505715ec2d76022c87\",\n      \"write\": null\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "_id": "<string>",
  "client_idp_id": "<string>",
  "org_id": "<string>",
  "name": "<string>",
  "issuer": "<string>",
  "jwks_uri": "<string>",
  "scope_claim_name": "<string>",
  "api_mappings": {
    "b84fe1a04e5648927971c0557971565c": {
      "scope_to_policy": {
        "read": "665d51505715ec2d76022c87"
      }
    }
  },
  "date_created": "2023-11-07T05:31:56Z",
  "last_updated": "2023-11-07T05:31:56Z"
}

Client IdPs

Bulk merge-patch API mappings.

RFC 7386 JSON Merge Patch on the api_mappings map. RFC 7386 applies recursively at every nesting level — the same null-to-delete, absent-key-untouched rules hold inside scope_to_policy as they do at the api_id level. The whole merge is one atomic document write, emitting exactly one NoticeClientIdPChanged notification regardless of how many keys are touched.

Remove an entire API mapping (null at the api_id level): json { "8ddd91f3cda9453442c477b06c4e2da4": null }

Remove a single scope while leaving the rest of the mapping intact (null at the scope_to_policy level): json { "b84fe1a04e5648927971c0557971565c": { "scope_to_policy": { "read": null } } }

Upsert a mapping and delete another in one call:

  "4c1c0d8fc885401053ddac4e39ef676b": { "scope_to_policy": { "read": "665d51505715ec2d76022c87" } },
  "8ddd91f3cda9453442c477b06c4e2da4": null
} ```

**Important:** to remove a scope key you must send it explicitly as `null`. Omitting a key from the patch body leaves it untouched at every level — there is no way to remove a scope by simply not including it.

PATCH

api

clientidps

{id}

mappings

Bulk merge-patch API mappings.

curl --request PATCH \
  --url https://{tenant}/api/clientidps/{id}/mappings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "4c1c0d8fc885401053ddac4e39ef676b": {
    "scope_to_policy": {
      "read": "665d51505715ec2d76022c87",
      "write": null
    }
  }
}
'

import requests

url = "https://{tenant}/api/clientidps/{id}/mappings"

payload = { "4c1c0d8fc885401053ddac4e39ef676b": { "scope_to_policy": {
            "read": "665d51505715ec2d76022c87",
            "write": None
        } } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    '4c1c0d8fc885401053ddac4e39ef676b': {scope_to_policy: {read: '665d51505715ec2d76022c87', write: null}}
  })
};

fetch('https://{tenant}/api/clientidps/{id}/mappings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{tenant}/api/clientidps/{id}/mappings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    '4c1c0d8fc885401053ddac4e39ef676b' => [
        'scope_to_policy' => [
                'read' => '665d51505715ec2d76022c87',
                'write' => null
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{tenant}/api/clientidps/{id}/mappings"

	payload := strings.NewReader("{\n  \"4c1c0d8fc885401053ddac4e39ef676b\": {\n    \"scope_to_policy\": {\n      \"read\": \"665d51505715ec2d76022c87\",\n      \"write\": null\n    }\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://{tenant}/api/clientidps/{id}/mappings")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"4c1c0d8fc885401053ddac4e39ef676b\": {\n    \"scope_to_policy\": {\n      \"read\": \"665d51505715ec2d76022c87\",\n      \"write\": null\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{tenant}/api/clientidps/{id}/mappings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"4c1c0d8fc885401053ddac4e39ef676b\": {\n    \"scope_to_policy\": {\n      \"read\": \"665d51505715ec2d76022c87\",\n      \"write\": null\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "_id": "<string>",
  "client_idp_id": "<string>",
  "org_id": "<string>",
  "name": "<string>",
  "issuer": "<string>",
  "jwks_uri": "<string>",
  "scope_claim_name": "<string>",
  "api_mappings": {
    "b84fe1a04e5648927971c0557971565c": {
      "scope_to_policy": {
        "read": "665d51505715ec2d76022c87"
      }
    }
  },
  "date_created": "2023-11-07T05:31:56Z",
  "last_updated": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization

string

header

required

The Tyk Dashboard API Access Credentials

Path Parameters

string

required

Internal record ID hex or custom client_idp_id.

Body

application/json

RFC 7386 JSON Merge Patch body for PATCH /api/clientidps/{id}/mappings. Each key is an api_id. A ScopeMappingPatch value upserts that mapping; a null value deletes the entire mapping for that api_id. Keys absent from the body are left untouched at every nesting level — this includes individual scope keys inside scope_to_policy. To remove a single scope, set it to null inside scope_to_policy; omitting it has no effect.

{key}

object | null

Patch shape for a single API's scope mapping. scope_to_policy is a free-form JSON object so that individual scope keys can be set to null (to remove them) as per RFC 7386 merge-patch semantics.

Show child attributes

Response

Mappings merged. Returns the full updated client IdP document.

A client Identity Provider stored beside API definitions.

_id

string

Internal record ID hex. Set server-side on creation.

client_idp_id

string

Stable user-facing identifier. Defaults to _id hex when not supplied on create.

org_id

string

Organisation ID. Set server-side from the session; cannot be overridden.

name

string

issuer

string

jwks_uri

string

scope_claim_name

string

JWT claim holding the OAuth scopes (e.g. scope, scp, roles). Empty falls back to scope gateway-side.

api_mappings

object

Map of api_id → ScopeMapping.

Show child attributes

Example:

{
  "b84fe1a04e5648927971c0557971565c": {
    "scope_to_policy": { "read": "665d51505715ec2d76022c87" }
  }
}

date_created

string<date-time>

last_updated

string<date-time>

⌘I

Overview

API Governance

Dashboard Analytics

User Management

Tyk Identity Broker (TIB)

Guides

Reference

Bulk merge-patch API mappings.

Authorizations

Path Parameters

Body

Response