Realm Assignments

Note: This API is only available if you're subscribed to Okta Identity Governance or Secure Partner Access. Contact your Customer Success Manager or Account Executive for more information.

The Realm Assignments API provides operations to manage realm assignments. See Realm assignments and Manage realms.

Note: When you create realm assignments in bulk, realm assignment priorities must be unique.

List all realm assignments
OAuth 2.0:
  • okta.realmAssignments.read

Lists all realm assignments

Request
query Parameters
limit
integer [ 1 .. 200 ]
Default: 20

A limit on the number of objects to return

after
string

The cursor used for pagination. It represents the priority of the last realm assignment returned in the previous fetch operation.

Responses
200

OK

403

Forbidden

429

Too Many Requests

get/api/v1/realm-assignments
Request samples 
Response samples 
application/json
[
  • {
    • "id": "rul2jy7jLUlnO3ng00g4",
    • "status": "ACTIVE",
    • "name": "Realm Assignment 1",
    • "created": "2022-04-04T15:56:05.000Z",
    • "lastUpdated": "2022-05-05T18:15:44.000Z",
    • "isDefault": false,
    • "domains": [
      ],
    • "conditions": {
      },
    • "actions": {
      },
    • "priority": 0,
    • "_links": {}
    },
  • {
    • "id": "rul2jy7jLUlnO5ng00g4",
    • "status": "ACTIVE",
    • "name": "Catch-all",
    • "created": "2022-04-04T15:56:05.000Z",
    • "lastUpdated": "2022-05-05T18:15:44.000Z",
    • "isDefault": true,
    • "domains": [
      ],
    • "conditions": {
      },
    • "actions": {
      },
    • "priority": 499,
    • "_links": {}
    }
]
Create a realm assignment
OAuth 2.0: 
  • okta.realmAssignments.manage
Creates a new realm assignment


Request 
Request Body schema: application/json
required
object (Actions) 
Action to apply to a user


 
object (AssignUserToRealm) 
Action that assigns a user to a realm


 
realmId
string
ID of the realm


 
object (Conditions) 
Conditions of applying realm assignment


 
object (Expression) 
Conditional expression


 
value
string
Value of the condition expression


 
profileSourceId
string
ID of the profile source


 
name
string
Name of the realm


 
priority
integer
The priority of the realm assignment. The lower the number, the higher the priority. This helps resolve conflicts between realm assignments. 




Note: When you create realm assignments in bulk, realm assignment priorities must be unique.




 
Responses 
201
Created


400
Bad Request


403
Forbidden


429
Too Many Requests


post/api/v1/realm-assignments
Request samples 
application/json
{
  • "actions": {
    • "assignUserToRealm": {
      }
    },
  • "conditions": {
    • "profileSourceId": "0oa4enoRyjwSCy5hx0g4",
    • "expression": {
      }
    },
  • "name": "Realm Assignment 1",
  • "priority": 0
}
Response samples 
application/json
{
  • "actions": {
    • "assignUserToRealm": {
      }
    },
  • "conditions": {
    • "expression": {
      },
    • "profileSourceId": "string"
    },
  • "created": "2019-08-24T14:15:22Z",
  • "domains": [ ],
  • "id": "string",
  • "isDefault": true,
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "priority": 0,
  • "status": "ACTIVE",
  • "_links": {
    • "self": {
      }
    }
}
List all realm assignment operations
OAuth 2.0: 
  • okta.realmAssignments.read
Lists all realm assignment operations. The upper limit is 200 and operations are sorted in descending order from most recent to oldest by ID.


Request 
query Parameters
limit
integer  [ 1 .. 200 ] 
 Default:  20
A limit on the number of objects to return


 
after
string
The cursor to use for pagination. It is an opaque string that specifies your current location in the list and is obtained from the Link response header. See Pagination.


 
Responses 
200
OK


403
Forbidden


429
Too Many Requests


get/api/v1/realm-assignments/operations
Request samples 
Response samples 
application/json
[
  • {
    • "id": "rre4mje4ez6B2a7B60g7",
    • "type": "realm:assignment",
    • "status": "COMPLETED",
    • "created": "2023-10-25T21:02:54.000Z",
    • "started": "2023-10-25T21:02:54.000Z",
    • "completed": "2023-10-25T21:02:54.000Z",
    • "realmId": "00g1b7rvh0xPLKXFf0g5",
    • "realmName": "Realm Name",
    • "assignmentOperation": {
      },
    • "numUserMoved": 50,
    • "_links": {}
    },
  • {
    • "id": "rre4mje4ez7B2a7B60g7",
    • "type": "realm:assignment",
    • "status": "COMPLETED",
    • "created": "2023-10-25T21:02:54.000Z",
    • "started": "2023-10-25T21:02:54.000Z",
    • "completed": "2023-10-25T21:02:54.000Z",
    • "assignmentOperation": {
      },
    • "numUserMoved": 50,
    • "_links": {}
    }
]
Execute a realm assignment
OAuth 2.0: 
  • okta.realmAssignments.manage
Executes a realm assignment


Request 
Request Body schema: application/json
required
assignmentId
string
ID of the realm


 
Responses 
201
Created


400
Bad Request


403
Forbidden


429
Too Many Requests


post/api/v1/realm-assignments/operations
Request samples 
application/json
{
  • "assignmentId": "0pr1b7rxZj2ibQzfP0g5"
}
Response samples 
application/json
{
  • "id": "rre4mje4ez6B2a7B60g7",
  • "type": "realm:assignment",
  • "status": "COMPLETED",
  • "created": "2023-10-25T21:02:54.000Z",
  • "started": "2023-10-25T21:02:54.000Z",
  • "completed": "2023-10-25T21:02:54.000Z",
  • "realmId": "00g1b7rvh0xPLKXFf0g5",
  • "realmName": "Realm Name",
  • "assignmentOperation": {
    • "configuration": {
      }
    },
  • "numUserMoved": 50,
  • "_links": {}
}
Retrieve a realm assignment
OAuth 2.0: 
  • okta.realmAssignments.read
Retrieves a realm assignment


Request 
path Parameters
assignmentId
required
string
ID of the realm assignment


 
 Example:  rul2jy7jLUlnO3ng00g4
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/realm-assignments/{assignmentId}
Request samples 
Response samples 
application/json
{
  • "id": "rul2jy7jLUlnO3ng00g4",
  • "status": "ACTIVE",
  • "name": "Realm Assignment 1",
  • "created": "2022-04-04T15:56:05.000Z",
  • "lastUpdated": "2022-05-05T18:15:44.000Z",
  • "isDefault": false,
  • "domains": [
    • "atko.com",
    • "user.com"
    ],
  • "conditions": {
    • "profileSourceId": "0oa4enoRyjwSCy5hx0g4",
    • "expression": {
      }
    },
  • "actions": {
    • "assignUserToRealm": {
      }
    },
  • "priority": 0,
  • "_links": {}
}
Replace a realm assignment
OAuth 2.0: 
  • okta.realmAssignments.manage
Replaces a realm assignment


Request 
path Parameters
assignmentId
required
string
ID of the realm assignment


 
 Example:  rul2jy7jLUlnO3ng00g4
Request Body schema: application/json
required
object (Actions) 
Action to apply to a user


 
object (AssignUserToRealm) 
Action that assigns a user to a realm


 
realmId
string
ID of the realm


 
object (Conditions) 
Conditions of applying realm assignment


 
object (Expression) 
Conditional expression


 
value
string
Value of the condition expression


 
profileSourceId
string
ID of the profile source


 
name
string
 
priority
integer
The priority of the realm assignment. The lower the number, the higher the priority. This helps resolve conflicts between realm assignments. 




Note: When you create realm assignments in bulk, realm assignment priorities must be unique.




 
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/realm-assignments/{assignmentId}
Request samples 
application/json
{
  • "actions": {
    • "assignUserToRealm": {
      }
    },
  • "conditions": {
    • "profileSourceId": "0oa4enoRyjwSCy5hx0g4",
    • "expression": {
      }
    },
  • "name": "Realm Assignment 1",
  • "priority": 0
}
Response samples 
application/json
{
  • "actions": {
    • "assignUserToRealm": {
      }
    },
  • "conditions": {
    • "expression": {
      },
    • "profileSourceId": "string"
    },
  • "created": "2019-08-24T14:15:22Z",
  • "domains": [ ],
  • "id": "string",
  • "isDefault": true,
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "priority": 0,
  • "status": "ACTIVE",
  • "_links": {
    • "self": {
      }
    }
}
Delete a realm assignment
OAuth 2.0: 
  • okta.realmAssignments.manage
Deletes a realm assignment


Request 
path Parameters
assignmentId
required
string
ID of the realm assignment


 
 Example:  rul2jy7jLUlnO3ng00g4
Responses 
204
No Content


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/realm-assignments/{assignmentId}
Request samples 
Response samples 
application/json
{
  • "errorCauses": [
    • {
      }
    ],
  • "errorCode": "string",
  • "errorId": "string",
  • "errorLink": "string",
  • "errorSummary": "string"
}
Activate a realm assignment
OAuth 2.0: 
  • okta.realmAssignments.manage
Activates a realm assignment


Request 
path Parameters
assignmentId
required
string
ID of the realm assignment


 
 Example:  rul2jy7jLUlnO3ng00g4
Responses 
204
No Content


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/realm-assignments/{assignmentId}/lifecycle/activate
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}
Deactivate a realm assignment
OAuth 2.0: 
  • okta.realmAssignments.manage
Deactivates a realm assignment


Request 
path Parameters
assignmentId
required
string
ID of the realm assignment


 
 Example:  rul2jy7jLUlnO3ng00g4
Responses 
204
No Content


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/realm-assignments/{assignmentId}/lifecycle/deactivate
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}