RAMP Plugin PKeys REST API | UFM REST API Guide

Authentication

Following authentication types are supported:

basic (/ufmRest)
client (/ufmRestV2)
token (/ufmRestV3)

General

Description – allow users to query the fabric to identify GUIDs assignments to PKeys
Request URL /ufmRestV2/plugin/ramp/pkeys
Actions
- Report a specific PKey or list of PKeys
- Report all PKeys
- Verify a specific PKey or list of PKeys
- Verify all PKeys
- Check Set GUIDs to PKey – monitor completion of a Set operation
- Check Add GUIDs to PKey – monitor completion of an Add operation
- Check Del PKey from GUIDs – monitor completion of a Delete operation
Note: All actions are performed asynchronously and require polling to provide the response when completed

Response to actions when started

     {
         "id": <jobid>,
         "action": "<action-name>",
         "status": "accepted"
     }

Report a Specific PKey (or List of PKeys)

Description – query the fabric to show which GUIDs have a specific PKey
Request URL – POST /ufmRestV2/plugin/ramp/pkeys
Request content type – Application/json
Action request parameter value – "REPORT"
Other request parameters

Name	Value	Default	Description	Mandatory/ Optional
action	"REPORT"	None	Name of action	Mandatory
entries	An array of objects. Each object has a "pkey" field	None	Each entry provides information about a PKey to report about	Mandatory, at least one entry
entries.pkey	Hexadecimal string between "0x0"-"0x7fff" exclusive	None	Network PKey	Mandatory
timeout	An integer between 1 and 200	30	Number of seconds to wait for the action to complete	Optional

Status Codes
- 202 – Accepted
- 400 – Bad Request
Response – "location" header contains query URL
- Location: pkeys/query?id=<jobid>

Request Data Example

     {
         "action": "REPORT",
         "entries": [
             {
                 "pkey": "0x1234"
             }
         ]
     }

Result – example of final response to query

     {
         "id": 11,
         "action": "REPORT",
         "status": "complete",
         "result": [
             {
                 "pkey": "0x1234",
                 "guids": [ "b8cef6030083bea2", "946dae03002ac882" ]
             }
         ]
     }

Report all PKeys

Description – query the fabric to show all PKeys and the GUIDs associated with them
Request URL – POST /ufmRestV2/plugin/ramp/pkeys
Request content type – Application/json
Action request parameter value – "REPORT"
Other request parameters

Name	Value	Default	Description	Mandatory/ Optional
action	"REPORT"	None	Name of action	Mandatory
all	true	None	All PKeys should be reported	Mandatory
timeout	An integer between 1 and 200	30	Number of seconds to wait for the action to complete	Optional

Status Codes
- 202 – Accepted
- 400 – Bad Request
Response – "location" header contains query URL
- Location: pkeys/query?id=<jobid>

Request Data Example

     {
         "action": "REPORT",
         "all": true
     }

Result – example of final response to query

     {
         "id": 12,
         "action": "REPORT",
         "status": "complete",
         "result": [
             {
                 "pkey": "0x1234",
                 "guids": [ "b8cef6030083bea2", "946dae03002ac882" ]
             },
             {
                 "pkey": "0x5678",
                 "guids": [ "b8cef6030083b777", "946dae03002ac111" ]
             }
         ]
     }

Verify a Specific PKey (or list of PKeys)

Description – query the fabric to show which of the GUIDs requested to have a specific PKey were configured accordingly
Request URL – POST /ufmRestV2/plugin/ramp/pkeys
Request content type – Application/json
Action request parameter value – "VERIFY"
Other request parameters

Name	Value	Default	Description	Mandatory/ Optional
action	"VERIFY"	None	Name of action	Mandatory
entries	An array of objects. Each object must have a "pkey" field	None	Each entry provides information about a PKey to report about	Mandatory, at least one entry
entries.pkey	Hexadecimal string between "0x0"-"0x7fff" exclusive	None	Network PKey	Mandatory
entries.guids	["…",… ".."] Each GUID is a hexadecimal string with a minimum length of 16 characters and maximum length of 20 characters	[]	A list of GUIDs presumed to be associated with the PKey. If not provided or empty, UFM will be queried to provide the list	Optional
timeout	An integer between 1 and 200	30	Number of seconds to wait for the action to complete	Optional

Status Codes
- 202 – Accepted
- 400 – Bad Request
Response – "location" header contains query URL
- Location: pkeys/query?id=<jobid>

Request Data Example

     {
         "action": "VERIFY",
         "entries": [
             {
                 "pkey": "0x1234"
             }
         ]
     }

Result – example of final response to query

     {
         "id": 13,
         "action": "VERIFY",
         "status": "complete",
         "result": [
             {
                 "pkey": "0x1234",
                 "guids": [ "b8cef6030083bea2", "946dae03002ac882" ],
                 "missing": [],
                 "wrong": []
             }
         ]
     }

Verify all PKeys

Description – query the fabric to show for all PKeys which of the GUIDs associated with each PKey have actually been configured
Request URL – POST /ufmRestV2/plugin/ramp/pkeys
Request content type – Application/json
Action request parameter value – "VERIFY"
Other request parameters

Name

Value

Default

Description

Mandatory/ Optional

action

"VERIFY"

None

Name of action

Mandatory

all

true

None

All PKeys should be verified.

UFM will be queried to provide the list (PKeys and GUIDs)

Mandatory

timeout

An integer between 1 and 200

Number of seconds to wait for the action to complete

Optional

Status Codes
- 202 – Accepted
- 400 – Bad Request
Response – "location" header contains query URL
- Location: pkeys/query?id=<jobid>

Request Data Example

     {
         "action": "VERIFY",
         "all": true
     }

Result – example of final response to query

     {
         "id": 14,
         "action": "VERIFY",
         "status": "complete",
         "result": [
             {
                 "pkey": "0x1234",
                 "guids": [ "b8cef6030083bea2", "946dae03002ac882" ],
                 "missing": [],
                 "wrong": []
             },
             {
                 "pkey": "0x5678",
                 "guids": [ "b8cef6030083b777", "946dae03002ac111" ],
                 "missing": [],
                 "wrong": []
             }
         ]
     }

Monitor Setting of GUIDs to a PKey

Description – Monitor the setting of a group of GUIDs to a PKey
Request URL – POST /ufmRestV2/plugin/ramp/pkeys
Request content type – Application/json
Action request parameter value – "CHKSET"
Other request parameters

Name	Value	Default	Description	Mandatory/ Optional
action	"CHKSET"	None	Name of action	Mandatory
entry	An object with a "pkey" field and a "guids" field	None	Each entry provides information about a PKey to report about	Mandatory
entry.pkey	Hexadecimal string between "0x0"-"0x7fff" exclusive	None	Network PKey	Mandatory
entry.guids	["…",… ".."] Each GUID is a hexadecimal string with a minimum length of 16 characters and maximum length of 20 characters	[]	A list of GUIDs presumed to be associated with the PKey.	Mandatory
timeout	Integer	30	Number of seconds to wait for the action to complete	Optional

Status Codes
- 202 – Accepted
- 400 – Bad Request
Response – "location" header contains query URL
- Location: pkeys/query?id=<jobid>

Request Data Example

     {
         "action": "CHKSET",
         "entry": {
             "pkey": "0x1234",
             "guids": [ "b8cef6030083bea2", "946dae03002ac882" ]
         },
         "timeout": 60
     }

Result – example of final response to query

     {
         "id": 15,
         "action": "CHKSET",
         "status": "complete",
         "result": [
             {
                 "pkey": "0x1234",
                 "guids": [ "b8cef6030083bea2", "946dae03002ac882" ]
             }
         ]
     }

Monitor Adding GUIDS to a PKey

Description – Monitor the assignment of a group of GUIDs to a PKey
Request URL – POST /ufmRestV2/plugin/ramp/pkeys
Request content type – Application/json
Action request parameter value – "CHKADD"
Other request parameters

Name	Value	Default	Description	Mandatory/Optional
action	"CHKADD"	None	Name of action	Mandatory
entry	An object with a "pkey" field and a "guids" field	None	Each entry provides information about a PKey to report about	Mandatory
entry.pkey	Hexadecimal string between "0x0"-"0x7fff" exclusive	None	Network PKey	Mandatory
entry.guids	["…",… ".."] Each GUID is a hexadecimal string with a minimum length of 16 characters and maximum length of 20 characters	[]	A list of GUIDs presumed to be associated with the PKey.	Mandatory
timeout	A number	30	Number of seconds to wait for the action to complete	Optional

Status Codes
- 202 – Accepted
- 400 – Bad Request
Response – "location" header contains query URL
- Location: pkeys/query?id=<jobid>

Request Data Example

     {
         "action": "CHKADD",
         "entry": {
             "pkey": "0x1234",
             "guids": [ "b8cef6030083bea2", "946dae03002ac882" ]
         },
         "timeout": 60
     }

Result – example of final response to query

     {
         "id": 16,
         "action": "CHKADD",
         "status": "complete",
         "result": [
             {
                 "pkey": "0x1234",
                 "guids": [ "b8cef6030083bea2", "946dae03002ac882" ]
             }
         ]
     }

Monitor Removing GUIDs from a PKey

Description – Monitor the removal of a group of GUIDs from a PKey
Request URL – POST /ufmRestV2/plugin/ramp/pkeys
Request content type – Application/json
Action request parameter value – "CHKDEL"
Other request parameters

Name	Value	Default	Description	Mandatory/Optional
action	"CHKDEL"	None	Name of action	Mandatory
entry	An object with a "pkey" field and a "guids" field	None	Each entry provides information about a PKey to report about	Mandatory
entry.pkey	Hexadecimal string between "0x0"-"0x7fff" exclusive	None	Network PKey	Mandatory
entry.guids	["…",… ".."] Each GUID is a hexadecimal string with a minimum length of 16 characters and maximum length of 20 characters	[]	A list of GUIDs presumed to be associated with the PKey.	Mandatory
timeout	A number	30	Number of seconds to wait for the action to complete	Optional

Status Codes
- 202 – Accepted
- 400 – Bad Request
Response – "location" header contains query URL
- Location: pkeys/query?id=<jobid>

Request Data Example

     {
         "action": "CHKDEL",
         "entry": {
             "pkey": "0x1234",
             "guids": [ "b8cef6030083bea2", "946dae03002ac882" ]
         },
         "timeout": 60
     }

Result – example of final response to query

     {
         "id": 17,
         "action": "CHKDEL",
         "status": "complete",
         "result": [
             {
                 "pkey": "0x1234",
                 "guids": [ "b8cef6030083bea2", "946dae03002ac882" ]
             }
         ]
     }

Query (Polling Request)

Description – Poll a pending action to check for a result
Request URL – GET /ufmRestV2/plugin/ramp/pkeys/query?id=<jobid>
Status Codes
- 200 – OK
- 400 – bad request

Response while action is still pending

     {
         "id": <jobid>,
         "action": "<action-name>",
         "status": "pending"
     }

Last updated: June 03, 2026