Oracle Access Governance REST APIs

Get Roles

post

/access-governance/access-reviews/20250331/campaigns/roles

Retrieves a list of roles for running access reviews.

Request

Query Parameters

limit: integer

Minimum Value: 1

Maximum Value: 1000

The maximum number of items to return.

Default Value: 10
page: string

Minimum Length: 1

A token representing the position at which to start retrieving results. This must come from the `opc-next-page` header field of a previous response.
sortBy: string

The field to sort by. Only one sort order may be provided. Default order for timeCreated is descending. Default order for displayName is ascending.

Default Value: timeCreated

Allowed Values: [ "timeCreated", "displayName" ]
sortOrder: string

The sort order to use, either 'ASC' or 'DESC'.

Allowed Values: [ "ASC", "DESC" ]

Header Parameters

opc-request-id: string

The client request ID for tracing. The only valid characters for request IDs are letters, numbers, underscore, and dash.

The filters to apply.

Root Schema : FilteredDetails

Type: object

The filters to apply

Show Source

campaignType: string

Allowed Values: [ "ACCESS", "OWNERSHIP" ]

Campaign type (ACCESS or OWNERSHIP). The default is ACCESS on backend.
criteria: array criteria

Maximum Number of Items: 20

The list of criteria
nameContains: string

Maximum Length: 100

The substring to match the name to
scope(required): string

Allowed Values: [ "GOVERNANCE_SYSTEM", "CLOUD_PROVIDER", "AG" ]

The scope of the campaign

{
    "type":"object",
    "description":"The filters to apply",
    "required":[
        "scope"
    ],
    "properties":{
        "criteria":{
            "type":"array",
            "description":"The list of criteria",
            "items":{
                "$ref":"#/definitions/Criteria"
            },
            "maxItems":20
        },
        "scope":{
            "description":"The scope of the campaign",
            "type":"string",
            "x-obmcs-top-level-enum":"#/definitions/CampaignScope",
            "enum":[
                "GOVERNANCE_SYSTEM",
                "CLOUD_PROVIDER",
                "AG"
            ]
        },
        "campaignType":{
            "description":"Campaign type (ACCESS or OWNERSHIP). The default is ACCESS on backend.",
            "type":"string",
            "x-obmcs-top-level-enum":"#/definitions/CampaignType",
            "enum":[
                "ACCESS",
                "OWNERSHIP"
            ]
        },
        "nameContains":{
            "type":"string",
            "description":"The substring to match the name to",
            "maxLength":100
        }
    }
}

Nested Schema : criteria

Type: array

Maximum Number of Items: 20

The list of criteria

Show Source

Array of: object Criteria

The criteria to use as a filter.

{
    "type":"array",
    "description":"The list of criteria",
    "items":{
        "$ref":"#/definitions/Criteria"
    },
    "maxItems":20
}

Nested Schema : Criteria

Type: object

The criteria to use as a filter.

Show Source

conditions: array conditions

Maximum Number of Items: 100

Filter condition (these conditions have an AND binding between them).
subCriteria: array subCriteria

The list of values of the criteria.
type(required): string

Allowed Values: [ "ORGANIZATION", "JOB_CODE", "IDENTITY_LOCATION", "RESOURCE", "RESOURCE_LOCATION", "ENTITLEMENT", "ROLE", "DOMAIN", "COMPARTMENT", "CLOUD_PROVIDER", "POLICY", "POLICY_CREATED", "CUSTOM_ATTRIBUTE", "CUSTOM_ATTRIBUTE_VALUE", "IDENTITY_COLLECTION", "IC_CREATED", "TARGET_IDENTITY", "TARGET", "GLOBAL_IDENTITY", "AM_WORKFLOW", "NOT_REVIEWED_SINCE", "ACCESS_GUARDRAIL", "GRANTED_PERMISSION_TYPE", "TEMPORAL_TYPE" ]

The type of the criteria.
value: array value

Maximum Number of Items: 500

The list of values of the criteria (these values have an OR binding between them).

{
    "type":"object",
    "description":"The criteria to use as a filter.",
    "required":[
        "type"
    ],
    "properties":{
        "type":{
            "type":"string",
            "description":"The type of the criteria.",
            "x-obmcs-top-level-enum":"#/definitions/CriteriaType",
            "enum":[
                "ORGANIZATION",
                "JOB_CODE",
                "IDENTITY_LOCATION",
                "RESOURCE",
                "RESOURCE_LOCATION",
                "ENTITLEMENT",
                "ROLE",
                "DOMAIN",
                "COMPARTMENT",
                "CLOUD_PROVIDER",
                "POLICY",
                "POLICY_CREATED",
                "CUSTOM_ATTRIBUTE",
                "CUSTOM_ATTRIBUTE_VALUE",
                "IDENTITY_COLLECTION",
                "IC_CREATED",
                "TARGET_IDENTITY",
                "TARGET",
                "GLOBAL_IDENTITY",
                "AM_WORKFLOW",
                "NOT_REVIEWED_SINCE",
                "ACCESS_GUARDRAIL",
                "GRANTED_PERMISSION_TYPE",
                "TEMPORAL_TYPE"
            ]
        },
        "value":{
            "type":"array",
            "description":"The list of values of the criteria (these values have an OR binding between them).",
            "items":{
                "type":"string"
            },
            "maxItems":500
        },
        "conditions":{
            "description":"Filter condition (these conditions have an AND binding between them).",
            "type":"array",
            "items":{
                "$ref":"#/definitions/Condition"
            },
            "maxItems":100
        },
        "subCriteria":{
            "type":"array",
            "description":"The list of values of the criteria.",
            "items":{
                "$ref":"#/definitions/Criteria"
            }
        }
    }
}

Nested Schema : conditions

Type: array

Maximum Number of Items: 100

Filter condition (these conditions have an AND binding between them).

Show Source

Array of: object Condition

The information about Condition.

{
    "description":"Filter condition (these conditions have an AND binding between them).",
    "type":"array",
    "items":{
        "$ref":"#/definitions/Condition"
    },
    "maxItems":100
}

Nested Schema : subCriteria

Type: array

The list of values of the criteria.

Show Source

Array of: object Criteria

The criteria to use as a filter.

{
    "type":"array",
    "description":"The list of values of the criteria.",
    "items":{
        "$ref":"#/definitions/Criteria"
    }
}

Nested Schema : value

Type: array

Maximum Number of Items: 500

The list of values of the criteria (these values have an OR binding between them).

Show Source

Array of: string

{
    "type":"array",
    "description":"The list of values of the criteria (these values have an OR binding between them).",
    "items":{
        "type":"string"
    },
    "maxItems":500
}

Nested Schema : Condition

Type: object

The information about Condition.

Show Source

additionalAttributes: object additionalAttributes

Additional Properties Allowed: additionalProperties

Additional attributes for additional information related to the condition.
basicCondition(required): object BasicCondition

The information about Condition.
childConditions: object BasicConditionCollection

Collection of conditions.
type(required): string

Allowed Values: [ "IDENTITY_ATTRIBUTE", "PERMISSION", "DOES_NOT_HAVE_PERMISSION" ]

The type for AG Resource.

{
    "type":"object",
    "required":[
        "basicCondition",
        "type"
    ],
    "properties":{
        "type":{
            "type":"string",
            "description":"The type for AG Resource.",
            "enum":[
                "IDENTITY_ATTRIBUTE",
                "PERMISSION",
                "DOES_NOT_HAVE_PERMISSION"
            ]
        },
        "basicCondition":{
            "$ref":"#/definitions/BasicCondition"
        },
        "childConditions":{
            "$ref":"#/definitions/BasicConditionCollection"
        },
        "additionalAttributes":{
            "type":"object",
            "description":"Additional attributes for additional information related to the condition.",
            "additionalProperties":{
                "type":"string"
            }
        }
    },
    "description":"The information about Condition."
}

Nested Schema : additionalAttributes

Type: object

Additional Properties Allowed

Show Source

string

{
    "type":"object",
    "description":"Additional attributes for additional information related to the condition.",
    "additionalProperties":{
        "type":"string"
    }
}

Additional attributes for additional information related to the condition.

Nested Schema : BasicCondition

Type: object

The information about Condition.

Show Source

dataType: string

Allowed Values: [ "STRING", "NUMBER", "BOOLEAN", "DATE" ]

Data type for the condition Identifier
displayName(required): string

Minimum Length: 1

Maximum Length: 255

Access Guardrails Identifier
lhs(required): string

Minimum Length: 1

Maximum Length: 512

Left hand side of the condition.
operator(required): string

Allowed Values: [ "EQ", "NE", "GT", "LT", "GTE", "LTE", "BEFORE", "AFTER", "TILL", "FROM", "BETWEEN", "NOT_BETWEEN", "IN", "NOT_IN", "CONTAINS", "NOT_CONTAINS", "BEGINS_WITH", "NOT_BEGINS_WITH", "ENDS_WITH", "NOT_ENDS_WITH", "IS_NULL", "IS_NOT_NULL", "EQUAL_WITH_NULL" ]

The operator for a access guardrail.
rhs(required): array rhs

Right hand side of the condition.
rhsUiDetails: array rhsUiDetails

Right hand side details of the condition.

{
    "type":"object",
    "required":[
        "displayName",
        "lhs",
        "operator",
        "rhs"
    ],
    "properties":{
        "displayName":{
            "type":"string",
            "description":"Access Guardrails Identifier",
            "minLength":1,
            "maxLength":255
        },
        "operator":{
            "type":"string",
            "description":"The operator for a access guardrail.",
            "enum":[
                "EQ",
                "NE",
                "GT",
                "LT",
                "GTE",
                "LTE",
                "BEFORE",
                "AFTER",
                "TILL",
                "FROM",
                "BETWEEN",
                "NOT_BETWEEN",
                "IN",
                "NOT_IN",
                "CONTAINS",
                "NOT_CONTAINS",
                "BEGINS_WITH",
                "NOT_BEGINS_WITH",
                "ENDS_WITH",
                "NOT_ENDS_WITH",
                "IS_NULL",
                "IS_NOT_NULL",
                "EQUAL_WITH_NULL"
            ],
            "x-obmcs-top-level-enum":"#/definitions/ConditionOperator"
        },
        "lhs":{
            "type":"string",
            "description":"Left hand side of the condition.",
            "minLength":1,
            "maxLength":512
        },
        "rhs":{
            "type":"array",
            "description":"Right hand side of the condition.",
            "items":{
                "type":"string"
            }
        },
        "rhsUiDetails":{
            "type":"array",
            "description":"Right hand side details of the condition.",
            "items":{
                "$ref":"#/definitions/UiDetail"
            }
        },
        "dataType":{
            "type":"string",
            "description":"Data type for the condition Identifier",
            "enum":[
                "STRING",
                "NUMBER",
                "BOOLEAN",
                "DATE"
            ],
            "x-obmcs-top-level-enum":"#/definitions/DataType"
        }
    },
    "description":"The information about Condition."
}

Nested Schema : BasicConditionCollection

Type: object

Collection of conditions.

Show Source

items(required): array items

List of condition.

{
    "type":"object",
    "required":[
        "items"
    ],
    "properties":{
        "items":{
            "type":"array",
            "description":"List of condition.",
            "items":{
                "$ref":"#/definitions/BasicCondition"
            }
        }
    },
    "description":"Collection of conditions."
}

Nested Schema : rhs

Type: array

Right hand side of the condition.

Show Source

Array of: string

{
    "type":"array",
    "description":"Right hand side of the condition.",
    "items":{
        "type":"string"
    }
}

Nested Schema : rhsUiDetails

Type: array

Right hand side details of the condition.

Show Source

Array of: object UiDetail

Ui detail for rendering values on UI

{
    "type":"array",
    "description":"Right hand side details of the condition.",
    "items":{
        "$ref":"#/definitions/UiDetail"
    }
}

Nested Schema : UiDetail

Type: object

Ui detail for rendering values on UI

Show Source

name(required): string

Name of value
value(required): string

Value

{
    "type":"object",
    "required":[
        "name",
        "value"
    ],
    "properties":{
        "name":{
            "type":"string",
            "description":"Name of value"
        },
        "value":{
            "type":"string",
            "description":"Value"
        }
    },
    "description":"Ui detail for rendering values on UI"
}

Nested Schema : items

Type: array

List of condition.

Show Source

Array of: object BasicCondition

The information about Condition.

{
    "type":"array",
    "description":"List of condition.",
    "items":{
        "$ref":"#/definitions/BasicCondition"
    }
}

Response

Supported Media Types

application/json

200 Response

A page of role summary objects.

Headers

opc-next-page: string

For pagination of a list of items. When paging through a list, if this header appears in the response, then a partial list might have been returned. Include this value as the `page` parameter for the subsequent GET request to get the next batch of items.
opc-request-id: string

Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Root Schema : RoleSummaryCollection

Type: object

Results of a role summary search.

Show Source

items(required): array items

List of role summaries.

{
    "type":"object",
    "description":"Results of a role summary search.",
    "required":[
        "items"
    ],
    "properties":{
        "items":{
            "description":"List of role summaries.",
            "type":"array",
            "items":{
                "$ref":"#/definitions/RoleSummary"
            }
        }
    }
}

Nested Schema : items

Type: array

List of role summaries.

Show Source

Array of: object RoleSummary

Role object summary.

{
    "description":"List of role summaries.",
    "type":"array",
    "items":{
        "$ref":"#/definitions/RoleSummary"
    }
}

Nested Schema : RoleSummary

Type: object

Role object summary.

Show Source

approvalWorkflowId: string

ApprovalWorkflowId that is applicable to the Role
createdBy: object IdInfo

Generic identifying information object.
customAttributes: object customAttributes

Metadata associated with the access bundle
description: string

Role description
id(required): string

Unique identifier that is immutable on creation
isOwner: boolean

Boolean value checking if logged-in user is owner of this resource or not.
name: string

Role name
owners: array owners

List of owner entities
primaryOwner: object PrimaryOwner

Details of a primary Owner.
requestableBy: string

Allowed Values: [ "ANY", "NONE" ]

The identity type that may request the Access Bundle.
status: string

Allowed Values: [ "ACTIVE", "DRAFT", "INACTIVE", "PENDING", "FAILED", "IN_PROGRESS", "SAVED", "SUCCESS", "TIMEOUT" ]

Status of the Role
tags: array tags

List of tags attached to the Role
timeCreated: string(date-time)

Time when the Role was created. An RFC3339 formatted datetime string
timeUpdated: string(date-time)

Time when the Role was last updated. An RFC3339 formatted datetime string

{
    "type":"object",
    "required":[
        "id"
    ],
    "properties":{
        "id":{
            "type":"string",
            "description":"Unique identifier that is immutable on creation"
        },
        "name":{
            "type":"string",
            "description":"Role name"
        },
        "description":{
            "type":"string",
            "description":"Role description"
        },
        "status":{
            "type":"string",
            "description":"Status of the Role",
            "enum":[
                "ACTIVE",
                "DRAFT",
                "INACTIVE",
                "PENDING",
                "FAILED",
                "IN_PROGRESS",
                "SAVED",
                "SUCCESS",
                "TIMEOUT"
            ],
            "x-obmcs-top-level-enum":"#/definitions/EntityStatus",
            "x-default-description":"ACTIVE"
        },
        "approvalWorkflowId":{
            "type":"string",
            "description":"ApprovalWorkflowId that is applicable to the Role"
        },
        "createdBy":{
            "$ref":"#/definitions/IdInfo"
        },
        "requestableBy":{
            "type":"string",
            "description":"The identity type that may request the Access Bundle.",
            "enum":[
                "ANY",
                "NONE"
            ],
            "x-obmcs-top-level-enum":"#/definitions/RequestableBy"
        },
        "timeCreated":{
            "type":"string",
            "format":"date-time",
            "description":"Time when the Role was created. An RFC3339 formatted datetime string"
        },
        "timeUpdated":{
            "type":"string",
            "format":"date-time",
            "description":"Time when the Role was last updated. An RFC3339 formatted datetime string"
        },
        "tags":{
            "type":"array",
            "description":"List of tags attached to the Role",
            "items":{
                "type":"string"
            }
        },
        "customAttributes":{
            "type":"object",
            "description":"Metadata associated with the access bundle",
            "properties":{
            }
        },
        "primaryOwner":{
            "$ref":"#/definitions/PrimaryOwner"
        },
        "isOwner":{
            "type":"boolean",
            "description":"Boolean value checking if logged-in user is owner of this resource or not."
        },
        "owners":{
            "type":"array",
            "description":"List of owner entities",
            "items":{
                "$ref":"#/definitions/OwnerSummary"
            }
        }
    },
    "description":"Role object summary."
}

Nested Schema : IdInfo

Type: object

Generic identifying information object.

Show Source

displayName: string

Display Name of the entity.
id: string

Id of the entity.
name: string

Name of the entity.

{
    "type":"object",
    "properties":{
        "id":{
            "type":"string",
            "description":"Id of the entity."
        },
        "name":{
            "type":"string",
            "description":"Name of the entity."
        },
        "displayName":{
            "type":"string",
            "description":"Display Name of the entity."
        }
    },
    "description":"Generic identifying information object."
}

Nested Schema : customAttributes

Type: object

Metadata associated with the access bundle

Show Source

{
    "type":"object",
    "description":"Metadata associated with the access bundle",
    "properties":{
    }
}

Nested Schema : owners

Type: array

List of owner entities

Show Source

Array of: object OwnerSummary

Owner entity object

{
    "type":"array",
    "description":"List of owner entities",
    "items":{
        "$ref":"#/definitions/OwnerSummary"
    }
}

Nested Schema : PrimaryOwner

Type: object

Details of a primary Owner.

Show Source

displayName: string

Display name of the primary Owner.
value: string

Id of the primary Owner.

{
    "type":"object",
    "properties":{
        "value":{
            "type":"string",
            "description":"Id of the primary Owner."
        },
        "displayName":{
            "type":"string",
            "description":"Display name of the primary Owner."
        }
    },
    "description":"Details of a primary Owner."
}

Nested Schema : tags

Type: array

List of tags attached to the Role

Show Source

Array of: string

{
    "type":"array",
    "description":"List of tags attached to the Role",
    "items":{
        "type":"string"
    }
}

Nested Schema : OwnerSummary

Type: object

Owner entity object

Show Source

id(required): string

Unique identifier that is immutable on creation
isPrimary(required): boolean

Is this entity the primary owner?
name(required): string

Name of the owner

{
    "type":"object",
    "required":[
        "id",
        "isPrimary",
        "name"
    ],
    "properties":{
        "id":{
            "type":"string",
            "description":"Unique identifier that is immutable on creation"
        },
        "name":{
            "type":"string",
            "description":"Name of the owner"
        },
        "isPrimary":{
            "type":"boolean",
            "description":"Is this entity the primary owner?"
        }
    },
    "description":"Owner entity object"
}

400 Response

Bad Request

Headers

opc-request-id: string

Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Root Schema : Error

Type: object

Error Information.

Show Source

code(required): string

A short error code that defines the error, meant for programmatic parsing.
message(required): string

A human-readable error string.

{
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "type":"string",
            "description":"A short error code that defines the error, meant for programmatic parsing."
        },
        "message":{
            "type":"string",
            "description":"A human-readable error string."
        }
    },
    "description":"Error Information."
}

401 Response

Unauthorized

Headers

opc-request-id: string

Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Root Schema : Error

Type: object

Error Information.

Show Source

code(required): string

A short error code that defines the error, meant for programmatic parsing.
message(required): string

A human-readable error string.

{
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "type":"string",
            "description":"A short error code that defines the error, meant for programmatic parsing."
        },
        "message":{
            "type":"string",
            "description":"A human-readable error string."
        }
    },
    "description":"Error Information."
}

404 Response

Not Found

Headers

opc-request-id: string

Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Root Schema : Error

Type: object

Error Information.

Show Source

code(required): string

A short error code that defines the error, meant for programmatic parsing.
message(required): string

A human-readable error string.

{
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "type":"string",
            "description":"A short error code that defines the error, meant for programmatic parsing."
        },
        "message":{
            "type":"string",
            "description":"A human-readable error string."
        }
    },
    "description":"Error Information."
}

429 Response

Too Many Requests

Headers

opc-request-id: string

Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Root Schema : Error

Type: object

Error Information.

Show Source

code(required): string

A short error code that defines the error, meant for programmatic parsing.
message(required): string

A human-readable error string.

{
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "type":"string",
            "description":"A short error code that defines the error, meant for programmatic parsing."
        },
        "message":{
            "type":"string",
            "description":"A human-readable error string."
        }
    },
    "description":"Error Information."
}

500 Response

Internal Server Error

Headers

opc-request-id: string

Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Root Schema : Error

Type: object

Error Information.

Show Source

code(required): string

A short error code that defines the error, meant for programmatic parsing.
message(required): string

A human-readable error string.

{
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "type":"string",
            "description":"A short error code that defines the error, meant for programmatic parsing."
        },
        "message":{
            "type":"string",
            "description":"A human-readable error string."
        }
    },
    "description":"Error Information."
}

Default Response

Unknown Error

Headers

opc-request-id: string

Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Root Schema : Error

Type: object

Error Information.

Show Source

code(required): string

A short error code that defines the error, meant for programmatic parsing.
message(required): string

A human-readable error string.

{
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "type":"string",
            "description":"A short error code that defines the error, meant for programmatic parsing."
        },
        "message":{
            "type":"string",
            "description":"A human-readable error string."
        }
    },
    "description":"Error Information."
}

Examples

The following example shows how to retrieve a list of roles available in Oracle Access Governance for review.

cURL Request Example

curl -i -L -X POST \
   -H "Authorization:Bearer <your long access token>" \
   -H "Content-Type:application/json" \
   -d \
'{
"criteria": [
    {
      "type": "CUSTOM_ATTRIBUTE",
      "value": [
        "organization.displayName"
      ],
      "subCriteria": [
        {
          "type": "CUSTOM_ATTRIBUTE_VALUE",
          "value": [
            "AG_CS_ORG"
          ]
        }
      ]
    }
  ],
  "scope": "AG",
  "campaignType": "ACCESS"
}' \
 '<${service-instance-url}/access-governance/access-reviews/${version}/campaigns/roles>'

Sample Request Payload

Select POST and add the following URL

${service-instance-url}/access-governance/access-reviews/${version}/campaigns/resources

{
"criteria": [
    {
      "type": "CUSTOM_ATTRIBUTE",
      "value": [
        "organization.displayName"
      ],
      "subCriteria": [
        {
          "type": "CUSTOM_ATTRIBUTE_VALUE",
          "value": [
            "AG_CS_ORG"
          ]
        }
      ]
    }
  ],
  "scope": "AG",
  "campaignType": "ACCESS"
}

Example of the Response Code

You'll receive 200 response with the following body:

{
  "items": [
    {
      "id": "85c6dd8f-XXXX-4794-a55d-878a34ac00dc",
      "name": "KY_Role_AWF",
      "displayName": "Workflow Admin Role",
      "description": "Grants administrative access to workflow configurations",
      "applicationName": "AccessWorkflowApp"
    },
    {
      "id": "9cf66b84-XXXX-42fe-a6d5-ee4f150e214f",
      "name": "KY_Role_NWF",
      "displayName": "Workflow Viewer Role",
      "description": "Allows read-only access to workflow data",
      "applicationName": "AccessWorkflowApp"
    }
  ]
}