Realms

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 Realms API provides operations to manage realms. See Manage realms.

List all realms
OAuth 2.0:
  • okta.realms.read

Lists all Realms

Request
query Parameters
limit
integer <int32>
Default: 200

Specifies the number of results returned. Defaults to 10 if search is provided.

after
string

The cursor used for pagination. It represents the last privileged resource ID returned in the previous fetch operation.

Example: after=oprbuthToCeLWOBwh0g4
search
string

Searches for realms with a supported filtering expression for most properties.

Searches for realms can be filtered by the contains (co) operator. You can only use co with the profile.name property. See Operators.

sortBy
string

Specifies the field to sort by and can be any single property (for search queries only)

Example: sortBy=profile.name
sortOrder
string
Default: "asc"

Specifies the sort order: asc or desc (for search queries only). This parameter is ignored if sortBy isn't present.

Responses
200

OK

403

Forbidden

429

Too Many Requests

get/api/v1/realms
Request samples 
Response samples 
application/json
[]
Create a realm
OAuth 2.0: 
  • okta.realms.manage
Creates a new realm


Request 
Request Body schema: application/json
required
object (RealmProfile) 
 
name
required
string
Name of a realm


 
realmType
string
Used to store partner users. This property must be set to PARTNER to access Okta's external partner portal.


 Enum: Description
PARTNER
Realm with external partner portal


DEFAULT
Default


 
Responses 
200
Success


400
Bad Request


403
Forbidden


429
Too Many Requests


post/api/v1/realms
Request samples 
application/json
{
  • "profile": {
    • "name": "string",
    • "realmType": "PARTNER"
    }
}
Response samples 
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "isDefault": true,
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "profile": {
    • "name": "string",
    • "realmType": "PARTNER"
    },
  • "_links": {
    • "self": {
      }
    }
}
Retrieve a realm
OAuth 2.0: 
  • okta.realms.read
Retrieves a realm


Request 
path Parameters
realmId
required
string
id of the Realm


 
 Example:  vvrcFogtKCrK9aYq3fgV
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/realms/{realmId}
Request samples 
Response samples 
application/json
{}
Replace the realm profile
OAuth 2.0: 
  • okta.realms.manage
Replaces the realm profile


Request 
path Parameters
realmId
required
string
id of the Realm


 
 Example:  vvrcFogtKCrK9aYq3fgV
Request Body schema: application/json
required
object (RealmProfile) 
 
name
required
string
Name of a realm


 
realmType
string
Used to store partner users. This property must be set to PARTNER to access Okta's external partner portal.


 Enum: Description
PARTNER
Realm with external partner portal


DEFAULT
Default


 
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/realms/{realmId}
Request samples 
application/json
{
  • "profile": {
    • "name": "string",
    • "realmType": "PARTNER"
    }
}
Response samples 
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "isDefault": true,
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "profile": {
    • "name": "string",
    • "realmType": "PARTNER"
    },
  • "_links": {
    • "self": {
      }
    }
}
Delete a realm
OAuth 2.0: 
  • okta.realms.manage
Deletes a realm permanently. This operation can only be performed after disassociating other entities like users and identity providers from a realm.


Request 
path Parameters
realmId
required
string
id of the Realm


 
 Example:  vvrcFogtKCrK9aYq3fgV
Responses 
204
No Content


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/realms/{realmId}
Request samples 
Response samples 
application/json
{
  • "errorCauses": [
    • {
      }
    ],
  • "errorCode": "string",
  • "errorId": "string",
  • "errorLink": "string",
  • "errorSummary": "string"
}