Labels

The Labels API enables you to categorize and organize resources such as apps, groups, entitlements, and collections. You can create, update, and assign key-value labels to resources to support automation, streamline configuration, and simplify the management of access reviews and requests.

Create a label
Beta
OAuth 2.0 scopes:
  • okta.governance.labels.manage
Admin roles:
  • SUPER_ADMIN

Creates a label that includes the key name of the label and its values

Request
Request Body schema: application/json
required
name
required
string [ 1 .. 50 ] characters

Key name of the label

required
Array of objects <= 10 items

List of label values

Responses
201

Resource label created successfully

400

A request failed validation

401

When authentication fails

403

When authorization fails

429

When the rate limit has been exceeded

500

When there is a server fault due to an unexpected error

post/governance/api/v1/labels
Request samples
application/json
{
  • "name": "Compliance",
  • "values": [
    • {
      • "name": "SOX",
      • "metadata": {
        }
      },
    • {
      • "name": "PII",
      • "metadata": {
        }
      }
    ]
}
Response samples
application/json
{
  • "labelId": "lbco3v6xlwdtEX2il1d6",
  • "name": "Compliance",
  • "values": [
    • {
      • "labelValueId": "lblo3v6xlwdtEX2il1d1",
      • "name": "SOX",
      • "metadata": {
        }
      },
    • {
      • "labelValueId": "lblo3v6xlwdtEX2il1d6",
      • "name": "PII",
      • "metadata": {
        }
      }
    ],
  • "_links": {
    • "self": {
      • "href": "/governance/api/v1/labels/lbco3v6xlwdtEX2il1d6"
      }
    }
}

List all labels
Beta
OAuth 2.0 scopes:
  • okta.governance.labels.read
Admin roles:
  • SUPER_ADMIN

Lists all labels

Request
query Parameters
filter
string <scim-filter>

A filter expression that returns entries based on the following properties and supported operators:

  • values.name: supports sw and co

Note: Query parameter percent encoding is required. See Special characters.

Examples:
filter=values.name sw "SOD"
filter=values.name co "SOD"
Responses
200

A list of labels

401

When authentication fails

403

When authorization fails

429

When the rate limit has been exceeded

500

When there is a server fault due to an unexpected error

get/governance/api/v1/labels
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "labelId": "lbco3v6xlwdtEX2il1d6",
      • "name": "Compliance",
      • "values": [
        ],
      • "_links": {
        }
      },
    • {
      • "labelId": "lbco3v6xlwdtEX2il1d7",
      • "name": "Security",
      • "values": [
        ],
      • "_links": {
        }
      }
    ],
  • "_links": {
    • "self": {
      • "href": "/governance/api/v1/labels"
      }
    }
}
Delete a label
Beta
OAuth 2.0 scopes: 
  • okta.governance.labels.manage
Admin roles: 
  • SUPER_ADMIN
Deletes a label key and its associated label values




Note: You can only delete a label key if there are no associated label values assigned to any resources.




Request 
path Parameters
labelId
required
string
The ID of the label


 
Responses 
204
Label deleted successfully


401
When authentication fails


403
When authorization fails


429
When the rate limit has been exceeded


500
When there is a server fault due to an unexpected error


delete/governance/api/v1/labels/{labelId}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000004",
  • "errorSummary": "Authentication failed.",
  • "errorLink": "E0000004",
  • "errorId": "oaeWCGz73hpRCG75VHP6-RRXw",
  • "errorCauses": [ ]
}
Retrieve a label
Beta
OAuth 2.0 scopes: 
  • okta.governance.labels.read
Admin roles: 
  • SUPER_ADMIN
Retrieves a single label


Request 
path Parameters
labelId
required
string
The ID of the label


 
Responses 
200
Resource label retrieved successfully


401
When authentication fails


403
When authorization fails


404
When the requested resource wasn't found


429
When the rate limit has been exceeded


500
When there is a server fault due to an unexpected error


get/governance/api/v1/labels/{labelId}
Request samples 
Response samples 
application/json
{
  • "labelId": "lbco3v6xlwdtEX2il1d6",
  • "name": "Compliance",
  • "values": [
    • {
      • "labelValueId": "lblo3v6xlwdtEX2il1d1",
      • "name": "SOX",
      • "metadata": {
        }
      },
    • {
      • "labelValueId": "lblo3v6xlwdtEX2il1d6",
      • "name": "PII",
      • "metadata": {
        }
      }
    ],
  • "_links": {
    • "self": {
      • "href": "/governance/api/v1/labels/lbco3v6xlwdtEX2il1d6"
      }
    }
}
Update a label
Beta
OAuth 2.0 scopes: 
  • okta.governance.labels.manage
Admin roles: 
  • SUPER_ADMIN
Updates the properties of a label


Request 
path Parameters
labelId
required
string
The ID of the label


 
Request Body schema: application/json
required
 Array ([ 1 .. 10 ] items)
op
required
string  non-empty 
The operation to perform a label update


 Value: "REPLACE"  
path
required
string
The path of the property to update.
Use the /name path to update the label category name.


 
refType
required
string
The label property for the update operation


 
value
string  <= 50 characters 
The value of the updated property


 
Responses 
200
Resource label updated successfully


400
A request failed validation


401
When authentication fails


403
When authorization fails


404
When the requested resource wasn't found


429
When the rate limit has been exceeded


500
When there is a server fault due to an unexpected error


patch/governance/api/v1/labels/{labelId}
Request samples 
application/json
Request body for updating label category


[
  • {
    • "op": "REPLACE",
    • "path": "/name",
    • "value": "Compliance",
    • "refType": "LABEL-CATEGORY"
    }
]
Response samples 
application/json
{
  • "labelId": "lbco3v6xlwdtEX2il1d6",
  • "name": "Compliance",
  • "values": [
    • {
      • "labelValueId": "lblo3v6xlwdtEX2il1d1",
      • "name": "SOX",
      • "metadata": {
        }
      },
    • {
      • "labelValueId": "lblo3v6xlwdtEX2il1d6",
      • "name": "PII",
      • "metadata": {
        }
      }
    ],
  • "_links": {
    • "self": {
      • "href": "/governance/api/v1/labels/lbco3v6xlwdtEX2il1d6"
      }
    }
}
List all labeled resources
Beta
OAuth 2.0 scopes: 
  • okta.governance.labels.read
Admin roles: 
  • SUPER_ADMIN
Lists all labeled resources




Note: If you create a custom admin role to view labeled resources, ensure that the custom role has permissions to view the resource and governance labels.
For example, to view labeled apps, the custom admin role must have the okta.apps.read and the okta.governance.labels.read permissions.




Request 
query Parameters
after
string
The pagination cursor that points to the last record of the previous request.


 
 Example:  after=00u68w6vzKLultXS97g6
filter
required
string <scim-filter> 
A filter expression that returns entries based on the following properties and supported operators:


    

  • orn:  supports eq
    • 

  • labelValueId: supports eq
    • 

  • resourceType: supports eq (The resourceType value is taken from the {objectType} attribute in the resource ORN. For example, entitlement-values for entitlement value resources.)
    • 





Note: Query parameter percent encoding is required. See Special characters.




  Examples: 
filter=orn eq "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ"
filter=labelValueId eq "lblo3v6xlwdtEX2il1d6" AND resourceType eq "apps"
filter=labelValueId eq "lblo3v6xlwdtEX2il1d6" AND resourceType eq "groups"
filter=labelValueId eq "ento3v6xlwdtEX2il1d6" AND resourceType eq "entitlement-values"
filter=labelValueId eq "ento3v6xlwdtEX2il1d6" AND resourceType eq "collections"
filter=(labelValueId eq "lblo3v6xlwdtEX2il1d6" OR labelValueId eq "lblo3v6xlwdtEX2il1d7") AND resourceType eq "apps"
filter=(labelValueId eq "lblo3v6xlwdtEX2il1d6" AND resourceType eq "apps") OR (labelValueId eq "lblo3v6xlwdtEX2il1d7" AND resourceType eq "groups")
limit
integer  [ 1 .. 200 ] 
 Default:  20
The maximum number of records returned in a response


 
Responses 
200
A list of resources with labels


401
When authentication fails


403
When authorization fails


429
When the rate limit has been exceeded


500
When there is a server fault due to an unexpected error


get/governance/api/v1/resource-labels
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "orn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ",
      • "profile": {
        },
      • "labels": [
        ]
      }
    ],
  • "_links": {
    • "self": {
      • "href": "/governance/api/v1/resource-labels?filter=orn eq \"orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ\""
      }
    }
}
Assign the labels to resources
Beta
OAuth 2.0 scopes: 
  • okta.governance.labels.manage
Admin roles: 
  • SUPER_ADMIN
Assigns the specified label values to resources




Note: If you create a custom admin role for assigning label values to resources, ensure that the custom role has permissions to edit the resource and governance labels.
For example, to assign labels to apps, the custom admin role must have the okta.apps.manage and the okta.governance.labels.manage permissions.




Request 
Request Body schema: application/json
required
labelValueIds
required
Array of strings  [ 1 .. 10 ] items 
Labels assigned to resources in the resourceOrns list


 
resourceOrns
required
Array of strings <okta-resource-orn>   [ 1 .. 10 ] items 
Resources assigned to labels (in ORN format)


 
Responses 
200
A list of resources with labels


400
A request failed validation


401
When authentication fails


403
When authorization fails


429
When the rate limit has been exceeded


500
When there is a server fault due to an unexpected error


post/governance/api/v1/resource-labels/assign
Request samples 
application/json
{
  • "resourceOrns": [
    • "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ",
    • "orn:okta:directory:00o11edPwGqbUrsDm0g4:groups:00g10ctakVI6XlTdk0g4",
    • "orn:okta:governance:00o11edPwGqbUrsDm0g4:entitlement-bundles:enbogpaj3XUzcM62u1d6",
    • "orn:okta:governance:00o11edPwGqbUrsDm0g4:collections:cologpaj3XUzcM62u1d6",
    • "orn:okta:governance:00o11rndFqmZ5rNfs0g4:entitlement-values:ent63C22YQoNMWOJf0g2"
    ],
  • "labelValueIds": [
    • "lblo3v6xlwdtEX2il1d1",
    • "lblo3v6xlwdtEX2il1d2"
    ]
}
Response samples 
application/json
{
  • "data": [
    • {
      • "orn": "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ",
      • "profile": {
        },
      • "labels": [
        ]
      },
    • {
      • "orn": "orn:okta:directory:00o11edPwGqbUrsDm0g4:groups:00g10ctakVI6XlTdk0g4",
      • "profile": {
        },
      • "labels": [
        ]
      },
    • {
      • "orn": "orn:okta:governance:00o11edPwGqbUrsDm0g4:entitlement-bundles:enbogpaj3XUzcM62u1d6",
      • "profile": {
        },
      • "labels": [
        ]
      },
    • {
      • "orn": "orn:okta:governance:00o11edPwGqbUrsDm0g4:collections:cologpaj3XUzcM62u1d6",
      • "profile": {
        },
      • "labels": [
        ]
      }
    ]
}
Remove the labels from resources
Beta
OAuth 2.0 scopes: 
  • okta.governance.labels.manage
Admin roles: 
  • SUPER_ADMIN
Removes the specified label values from resources




Note: If you create a custom admin role for assigning and unassigning labels to resources, ensure that the custom role has permissions to edit the resource and governance labels.
For example, to unassign labels from apps, the custom admin role must have the okta.apps.manage and the okta.governance.labels.manage permissions.




Request 
Request Body schema: application/json
required
labelValueIds
required
Array of strings  [ 1 .. 10 ] items 
Labels assigned to resources in the resourceOrns list


 
resourceOrns
required
Array of strings <okta-resource-orn>   [ 1 .. 10 ] items 
Resources assigned to labels (in ORN format)


 
Responses 
204
Label deleted successfully


400
A request failed validation


401
When authentication fails


403
When authorization fails


429
When the rate limit has been exceeded


500
When there is a server fault due to an unexpected error


post/governance/api/v1/resource-labels/unassign
Request samples 
application/json
{
  • "resourceOrns": [
    • "orn:okta:idp:00o11edPwGqbUrsDm0g4:apps:oidc:0oafxqCAJWWGELFTYASJ",
    • "orn:okta:directory:00o11edPwGqbUrsDm0g4:groups:00g10ctakVI6XlTdk0g4",
    • "orn:okta:governance:00o11edPwGqbUrsDm0g4:entitlement-bundles:enbogpaj3XUzcM62u1d6",
    • "orn:okta:governance:00o11edPwGqbUrsDm0g4:collections:cologpaj3XUzcM62u1d6",
    • "orn:okta:governance:00o11rndFqmZ5rNfs0g4:entitlement-values:ent63C22YQoNMWOJf0g2"
    ],
  • "labelValueIds": [
    • "lblo3v6xlwdtEX2il1d2"
    ]
}
Response samples 
application/json
{
  • "errorCode": "string",
  • "errorId": "string",
  • "errorSummary": "string",
  • "errorLink": "string",
  • "errorCauses": [
    • {
      • "errorSummary": "string",
      • "reason": "string",
      • "location": "string",
      • "locationType": "string",
      • "domain": "string"
      }
    ]
}