Assign a collection to principals

Okta Identity Governance

Management APIs

Assign a collection to principals

Request

OAuth 2.0 scope:

okta.governance.collections.manage

Admin roles:

APP_ADMIN

Assigns a collection to principals

The assignment can be for a limited time or indefinite. This operation is idempotent. If the assignment already exists, it's updated with the new values.

Path

collectionIdstringrequired

Unique identifier for the collection

Bodyapplication/jsonrequired

Attributes of collection assignment

Array [

expirationTimestring, (date-time)

The date on which the principal's access expires. This property is specified in ISO 8601 duration format.

timeZonestring, [ 1 .. 64 ] characters

The time zone, in IANA format, for the end date of the user access

principalobject(target-principal-full)

Representation of a principal

actorstring(grant-actor)

The flow that triggered the grant request

Default:"API"

Enum Value	Description
API	The grant request was triggered from the API.
ACCESS_REQUEST	The grant request was triggered from an access request.
NONE	The grant request wasn't triggered from the API, an access request, or the Admin Console.
ADMIN	The grant request was triggered from the Admin Console.

collectionIdstring, (collection-id), = 20 characters(collection-id)col[0-9a-zA-Z]+

The resource collection id

]

Assign principals to the collection. The assignment can be for a limited time or indefinite.

curl -i -X POST \
  'https://subdomain.okta.com/governance/api/v2/collections/{collectionId}/assignments' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "actor": "ACCESS_REQUEST",
      "principal": {
        "externalId": "00u174cGuGxVFp4EY0g4",
        "type": "OKTA_USER"
      },
      "expirationTime": "2024-04-30T23:59:59Z",
      "timeZone": "America/Toronto"
    },
    {
      "actor": "ACCESS_REQUEST",
      "principal": {
        "externalId": "00u174cGuGxVFp4EY0g5",
        "type": "OKTA_USER"
      }
    }
  ]'

Responses

A list of assigned principals

Headers

Linkstring

A link to self and next.

Note: next is only present if there's another page of results.

X-Rate-Limit-Limitinteger, >= 1required

The rate-limit ceiling for the current request

Example:60

X-Rate-Limit-Remaininginteger, >= 0required

The number of requests left for the current rate-limit window

Example:60

X-Rate-Limit-Resetinteger, >= 0required

The time when the rate limit resets, specified in UTC epoch time (in seconds)

Example:1609459200

Bodyapplication/json

Array [

expirationTimestring, (date-time)

The date on which the principal's access expires. This property is specified in ISO 8601 duration format.

timeZonestring, [ 1 .. 64 ] characters

The time zone, in IANA format, for the end date of the user access

principalobject(target-principal-full)

Representation of a principal

actorstring(grant-actor-full)

The flow that triggered the grant. Includes system-set values that can appear on read responses but can't be submitted on write requests.

Default:"API"

Enum Value	Description
API	The grant request was triggered from the API.
ACCESS_REQUEST	The grant request was triggered from an access request.
NONE	The grant request wasn't triggered from the API, an access request, or the Admin Console.
ADMIN	The grant request was triggered from the Admin Console.

collectionIdstring, (collection-id), = 20 characters(collection-id)col[0-9a-zA-Z]+

The resource collection id

idstring, = 20 characters

The assignment id

assignmentTypestring(principal-assignment-type)

Collection assignment type or source

Default:"INDIVIDUAL"

Value:"INDIVIDUAL"

]

Response

List of assigned users to a collection

[
  {
    "id": "ass28w6vzKKultXP98g5",
    "actor": "ACCESS_REQUEST",
    "principal": { … },
    "expirationTime": "2024-04-30T23:59:59Z",
    "timeZone": "America/Toronto",
    "assignmentType": "INDIVIDUAL"
  },
  {
    "id": "ass28w6vzKKultXP98g6",
    "actor": "ACCESS_REQUEST",
    "principal": { … },
    "assignmentType": "INDIVIDUAL"
  }
]