Resource types over REST

You can manage resource types over REST at the resourcetypes endpoint.

PingOne Advanced Identity Cloud stores resource types as JSON objects. A resource type can include the following fields. The fields have JSON values—strings, numbers, objects, sets, arrays, true, false, and null.

Resource type field Description

Resource type field	Description
`_id`, `uuid`⁽¹⁾	A unique, system-generated UUID string. Use this string to identify a specific resource type. Do not change the generated UUID.
`_rev`⁽¹⁾	A system-generated revision string.
`name`	A human-readable name string for the resource type. Do not use any of the following characters in policy, policy set, or resource type names: Double quotes (`"`) Plus sign (`+`) Comma (`,`) Less than (`<`) Equals (`=`) Greater than (`>`) Backslash (`\`) Forward slash (`/`) Semicolon (`;`) Null (`\u0000`)
`description`	An optional text string to help identify the resource type.
`patterns`	An array of resource pattern strings specifying URLs or resource names to protect. For details, refer to Resource type patterns.
`actions`	An object where each field is an action name. The value for each action name field is a boolean indicating whether to allow the action by default in policies that derive from this resource type.
`createdBy`⁽¹⁾	A string indicating who created the resource type.
`creationDate`⁽¹⁾	An integer containing the creation time in milliseconds since January 1, 1970.
`lastModifiedBy`⁽¹⁾	A string indicating who last changed the resource type.
`lastModifiedDate`⁽¹⁾	An integer containing the last modified time in milliseconds since January 1, 1970.

_id, uuid⁽¹⁾

A unique, system-generated UUID string.

Use this string to identify a specific resource type. Do not change the generated UUID.

_rev⁽¹⁾

A system-generated revision string.

name

A human-readable name string for the resource type.

Do not use any of the following characters in policy, policy set, or resource type names:

Double quotes (")
Plus sign (+)
Comma (,)
Less than (<)
Equals (=)
Greater than (>)
Backslash (\)
Forward slash (/)
Semicolon (;)
Null (\u0000)

description

An optional text string to help identify the resource type.

patterns

An array of resource pattern strings specifying URLs or resource names to protect.

For details, refer to Resource type patterns.

actions

An object where each field is an action name.

The value for each action name field is a boolean indicating whether to allow the action by default in policies that derive from this resource type.

createdBy⁽¹⁾

A string indicating who created the resource type.

creationDate⁽¹⁾

An integer containing the creation time in milliseconds since January 1, 1970.

lastModifiedBy⁽¹⁾

A string indicating who last changed the resource type.

lastModifiedDate⁽¹⁾

An integer containing the last modified time in milliseconds since January 1, 1970.

⁽¹⁾ Do not change the value of this field.

Access the endpoints

The REST calls to manage resource types rely on an account with the appropriate privileges:

Create a resource type administrator.

In the Advanced Identity Cloud admin UI, select Identities > Manage > Realm Name Realm - Users > + New Realm Name Realm - User and fill the required fields.

Record the username and password.
Create a group that grants the privileges to the resource type administrator.

Under Native Consoles > Access Management, select Realms > Realm Name > Identities > Groups > + Add Group to create a group with the following settings:

Group ID

am-resource-type-admins

Members

The resource type administrator whose username you recorded

Privileges

Policy Admin
Resource Type Modify Access
Resource Type Read Access

Before making REST calls to manage resource types, authenticate as the resource type administrator:

$ curl \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-OpenAM-Username: <resource-type-admin-username>' \
--header 'X-OpenAM-Password: <resource-type-admin-password>' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{"tokenId":"<resource-type-admin-tokenId>","successUrl":"/enduser/?realm=/alpha","realm":"/alpha"}

For additional details, refer to Session tokens after authentication.

Use the <resource-type-admin-tokenId> as the value of the <session-cookie-name> header to access the REST endpoints.

Query resource types

To list all the resource types defined for a realm, send an HTTP GET request to the /json/realms/root/realms/Realm Name/resourcetypes endpoint with _queryFilter=true as the query string parameter.

$ curl \
--header "<session-cookie-name>: <resource-type-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/resourcetypes?_queryFilter=true'
[{
  "result": [{
    "_id": "fcaee7dc-f99c-43b1-b10d-592e1c4bd394",
    "uuid": "fcaee7dc-f99c-43b1-b10d-592e1c4bd394",
    "name": "Light",
    "description": "",
    "patterns": ["light://*/*"],
    "actions": {
      "switch_off": false,
      "switch_on": false
    },
    "createdBy": "id=a980a458-2654-4d4f-a12a-d4bfa39534f7,ou=user,ou=am-config",
    "creationDate": 1669038769034,
    "lastModifiedBy": "id=a980a458-2654-4d4f-a12a-d4bfa39534f7,ou=user,ou=am-config",
    "lastModifiedDate": 1669038769034
  }, {
    "_id": "76656a38-5f8e-401b-83aa-4ccb74ce88d2",
    "uuid": "76656a38-5f8e-401b-83aa-4ccb74ce88d2",
    "name": "URL..."
  }, {
    "_id": "d60b7a71-1dc6-44a5-8e48-e4b9d92dee8b",
    "uuid": "d60b7a71-1dc6-44a5-8e48-e4b9d92dee8b",
    "name": "OAuth2 Scope..."
  }],
  "resultCount": 3,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": 0
}

Adapt the query string parameters to refine the results.

Field Supported _queryFilter operators

Field	Supported `_queryFilter` operators
`uuid`	Equals (`eq`) Contains (`co`) Starts with (`sw`)
`name`
`description`
`patterns`
`actions`

uuid

Equals (eq)
Contains (co)
Starts with (sw)

name

description

patterns

actions

Read a resource type

To read a resource type in a realm, send an HTTP GET request to the /json/realms/root/realms/Realm Name/resourcetypes/uuid endpoint, where uuid is the value of the "uuid" field for the resource.

$ curl \
--header "<session-cookie-name>: <resource-type-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/resourcetypes/fcaee7dc-f99c-43b1-b10d-592e1c4bd394'
{
  "_id": "fcaee7dc-f99c-43b1-b10d-592e1c4bd394",
  "_rev": "1669045336245",
  "uuid": "fcaee7dc-f99c-43b1-b10d-592e1c4bd394",
  "name": "Light",
  "description": "",
  "patterns": ["light://*/*"],
  "actions": {
    "switch_off": false,
    "switch_on": false
  },
  "createdBy": "id=a980a458-2654-4d4f-a12a-d4bfa39534f7,ou=user,ou=am-config",
  "creationDate": 1669038769034,
  "lastModifiedBy": "id=a980a458-2654-4d4f-a12a-d4bfa39534f7,ou=user,ou=am-config",
  "lastModifiedDate": 1669038769034
}

Create a resource type

To create a resource type in a realm, send an HTTP POST request to the /json/realms/root/realms/Realm Name/resourcetypes endpoint with _action=create as the query string parameter and a JSON representation of the resource type as the POST data.

PingOne Advanced Identity Cloud generates the UUID for the resource.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: <resource-type-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
--data '{
  "name": "My Resource Type",
  "actions": {
    "LEFT": true,
    "RIGHT": true,
    "UP": true,
    "DOWN": true
  },
  "patterns": ["https://device/location/*"]
}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/resourcetypes/?_action=create'
{
  "_id": "c7e09ca1-a0db-4434-9327-ca685ae99899",
  "uuid": "c7e09ca1-a0db-4434-9327-ca685ae99899",
  "name": "My Resource Type",
  "description": null,
  "patterns": ["https://device/location/*"],
  "actions": {
    "RIGHT": true,
    "DOWN": true,
    "UP": true,
    "LEFT": true
  },
  "createdBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
  "creationDate": 1669045619375,
  "lastModifiedBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
  "lastModifiedDate": 1669045619375
}

Update a resource type

To update a resource type in a realm, send an HTTP PUT request to the /json/realms/root/realms/Realm Name/resourcetypes/uuid endpoint, where uuid is the value of the "uuid" field for the resource. Include a JSON representation of the resource type as the PUT body, making sure the "uuid" and "_id" fields match the original resource.

$ curl \
--request PUT \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: <resource-type-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
--data '{
  "name": "My Resource Type",
  "actions": {
    "LEFT": true,
    "RIGHT": true,
    "UP": false,
    "DOWN": false
  },
  "patterns": ["https://device/location/*"]
}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/resourcetypes/c7e09ca1-a0db-4434-9327-ca685ae99899'
{
  "_id": "c7e09ca1-a0db-4434-9327-ca685ae99899",
  "uuid": "c7e09ca1-a0db-4434-9327-ca685ae99899",
  "name": "My Resource Type",
  "description": null,
  "patterns": ["https://device/location/*"],
  "actions": {
    "RIGHT": true,
    "DOWN": false,
    "UP": false,
    "LEFT": true
  },
  "createdBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
  "creationDate": 1669045619375,
  "lastModifiedBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
  "lastModifiedDate": 1669045765822
}

Delete a resource type

To delete a resource type from a realm, send an HTTP DELETE request to the /json/realms/root/realms/Realm Name/resourcetypes/uuid endpoint, where uuid is the value of the "uuid" field for the resource.

$ curl \
--request DELETE \
--header "<session-cookie-name>: <resource-type-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/resourcetypes/c7e09ca1-a0db-4434-9327-ca685ae99899'
{"_id":"c7e09ca1-a0db-4434-9327-ca685ae99899","_rev":"0"}

PingOne Advanced Identity Cloud does not permit deletion of a resource type when a policy set or policy depends on it. If you attempt to delete a resource type that is in use, PingOne Advanced Identity Cloud returns an HTTP 409 Conflict status code and a message like the one in the following example:

$ curl \
--request DELETE \
--header "<session-cookie-name>: <resource-type-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/resourcetypes/76656a38-5f8e-401b-83aa-4ccb74ce88d2'
{
  "code": 409,
  "reason": "Conflict",
  "message": "Unable to remove resource type 76656a38-5f8e-401b-83aa-4ccb74ce88d2 because it is referenced in the policy model."
}

Remove the dependency on the resource type from all policy sets and policies before you delete it.