Schemas

The Schemas API provides operations to manage custom User profiles as well as endpoints to discover the structure of the Log Stream configuration.

Okta's Universal Directory allows administrators to define custom User profiles for Okta Users and Applications. Okta adopts a subset of JSON Schema Draft 4 as the schema language to describe and validate extensible User profiles. For Log Stream Schemas, Okta uses JSON Schema Draft 2020-12. JSON Schema is a lightweight declarative format for describing the structure, constraints, and validation of JSON documents.

Note: Okta implements only a subset of JSON Schema Draft 4 and JSON Schema Draft 2020-12. This document describes which parts apply to Okta, and any extensions Okta has made to JSON Schema Draft 4 and JSON Schema Draft 2020-12.

Unique Attributes

You can enforce uniqueness for custom properties in Okta user profiles or the Okta group profile, such as an employee identification number. You can declare a maximum of five unique properties for each user type and five unique properties in the Okta group profile. Different user types can have the same or different unique properties (up to the limit of five per type).

Unique properties in Okta user profiles share a single namespace across all user types in an org. If user types A and B both contain the property ice cream and you identify it as unique in both profiles, then if a user of type A has the value chocolate, no other users of type A or B (or any other user type that declares ice cream as unique) can have that value.

Properties that aren't unique also aren't tracked for uniqueness. Suppose the property candy is unique in type E and not unique in type F. If a user of type E has the value caramel for the candy property, no other users of type E can also have the value caramel, but any number of users of type F can already have or later be assigned the value caramel. Furthermore, because candy is not unique in type F, any values users of type F may have are not considered when enforcing uniqueness for users of type E. No matter how many users of type F already have the value cotton, it might be assigned to a user of type E as long as no other such user already has that value.

If you attempt to create or update a user with a duplicate value for a custom user property with a uniqueness restriction, the user creation or update operation fails. The user isn't created or updated until you enter a unique value. Similarly, creating or updating a group fails when the request contains a value for a unique custom group property that is duplicated by another group.

null values don't enter into the uniqueness calculation. If the unique property isn't also specified as being required, you can also omit the value entirely. Multiple users or groups can omit the property and not violate uniqueness.

To enforce uniqueness for custom properties, you can either add new unique custom properties or update existing custom properties to be unique.

Add new unique custom property

You can use the add property to user profile schema request or the add property to group profile schema request to add one or more unique custom user or group properties. Specify "unique": true on the properties to be marked as unique. The response shows the properties with "unique": "UNIQUE_VALIDATED" and uniqueness is then enforced on those properties.

Update existing custom property to be unique

You can use the update user profile schema property request or the update group profile schema property request to mark existing custom user or group properties as unique by specifying "unique": true on the properties to be marked as unique.

After the request to mark existing custom properties as unique is submitted, an asynchronous validation check is performed to make sure that there are no existing duplicate entries. If you have a significant number of users or groups, the validation can take some time.

A uniqueness status of "unique": "PENDING_UNIQUENESS" indicates that the validation check is still in progress. Use the Universal Directory page in the Admin Console (Directory > Directory Integrations) to track the status of the validation check. After the validation completes, if you submit a retrieve user schema request or a retreive group schema request, the property's uniqueness status changes to UNIQUE_VALIDATED if no duplicate records are found, and uniqueness is then enforced on that property. Otherwise, if duplicate records are found, the unique attribute of the schema property isn't shown in the get schema request and uniqueness isn't enforced on the schema property.

Update existing unique custom property to be non-unique

You can use the update user profile schema property request or the update group profile schema property request to change existing unique custom user or group properties to be non-unique by specifying "unique": false on the properties to be changed to non-unique. The response shows the properties without the unique attribute and the uniqueness constraint is then removed on those properties.

Note: If multiple user types declare a property as unique and you remove the uniqueness constraint on one type, there may be a delay before users of other types that declare the property as unique can be assigned values formerly held by users of the first type.

Retrieve the default App User Schema for an App
OAuth 2.0: okta.schemas.read

Retrieves the default Schema for an App User.

The User Types feature does not extend to apps. All users assigned to a given app use the same App User Schema. Therefore, unlike the User Schema operations, the App User Schema operations all specify default and don't accept a Schema ID.

Request
path Parameters
appId
required
string

Application ID

Example: 0oafxqCAJWWGELFTYASJ
Responses
200

successful operation

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/meta/schemas/apps/{appId}/default
Request samples 
Response samples 
application/json
{
  • "$schema": "string",
  • "created": "string",
  • "definitions": {
    • "base": {
      },
    • "custom": {
      }
    },
  • "id": "string",
  • "lastUpdated": "string",
  • "name": "string",
  • "properties": {
    • "profile": {
      }
    },
  • "title": "string",
  • "type": "string",
  • "_links": {
    • "self": {
      }
    }
}
Update the App User Profile Schema for an App
OAuth 2.0: okta.schemas.manage
Updates the App User Schema. This updates, adds, or removes one or more custom profile properties or the nullability of a base property in the App User Schema for an app. Changing a base property's nullability (for example, the value of its required field) is allowed only if it is nullable in the default predefined Schema for the App.


The User Types feature does not extend to apps. All users assigned to a given app use the same App User Schema. Therefore, unlike the User Schema operations, the App User Schema operations all specify default and don't accept a Schema ID.


Request 
path Parameters
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
Request Body schema: application/json
optional
object
User Profile subschemas


The Profile object for a User is defined by a composite Schema of base and custom properties using a JSON path to reference subschemas. The #base properties are defined and versioned by Okta, while #custom properties are extensible. Custom property names for the Profile object must be unique and can't conflict with a property name defined in the #base subschema.


 
object (UserSchemaBase) 
All Okta-defined Profile properties are defined in a Profile subschema with the resolution scope #base. You can't modify these properties, except to update permissions, to change the nullability of firstName and lastName, or to specify a pattern for login. They can't be removed.


The base User Profile is based on the System for Cross-domain Identity Management: Core Schema and has the standard properties detailed below.


 
object
The #base object properties


 
object (UserSchemaPublic) 
All custom Profile properties are defined in a Profile subschema with the resolution scope #custom


 
object
The #custom object properties


 
object
User Object Properties


 
object (UserSchemaPropertiesProfile) 
 
Array of objects (UserSchemaPropertiesProfileItem) 
 
title
string
User-defined display name for the Schema


 
Responses 
200
successful operation


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/meta/schemas/apps/{appId}/default
Request samples 
application/json
{
  • "definitions": {
    • "custom": {
      }
    }
}
Response samples 
application/json
{
  • "id": "https://{yourOktaDomain}/meta/schemas/apps/0oa25gejWwdXNnFH90g4/default",
  • "$schema": "http://json-schema.org/draft-04/schema#",
  • "name": "Example App",
  • "title": "Example App User",
  • "lastUpdated": "2017-07-18T23:18:43.000Z",
  • "created": "2017-07-18T22:35:30.000Z",
  • "definitions": {
    • "base": {
      },
    • "custom": {
      }
    },
  • "type": "object",
  • "properties": {
    • "profile": {
      }
    }
}
Retrieve the default Group Schema
OAuth 2.0: okta.schemas.read
Retrieves the Group Schema


The User Types feature does not extend to groups. All groups use the same Group Schema. Unlike User Schema operations, Group Schema operations all specify default and don't accept a Schema ID.


Responses 
200
successful operation


403
Forbidden


429
Too Many Requests


get/api/v1/meta/schemas/group/default
Request samples 
Response samples 
application/json
{
  • "$schema": "http://json-schema.org/draft-04/schema#",
  • "_links": {},
  • "created": "2021-01-30T00:18:24.000Z",
  • "definitions": {
    • "base": {
      },
    • "custom": {
      }
    },
  • "description": "Okta group profile template",
  • "id": "https://{yourOktaDomain}/meta/schemas/group/default",
  • "lastUpdated": "2021-02-25T23:05:31.000Z",
  • "name": "group",
  • "properties": {
    • "profile": {
      }
    },
  • "title": "Okta group",
  • "type": "object"
}
Update the Group Profile Schema
OAuth 2.0: okta.schemas.manage
Updates the Group Profile schema. This updates, adds, or removes one or more custom profile properties in a Group Schema. Currently Okta does not support changing base Group Profile properties.


The User Types feature does not extend to groups. All groups use the same Group Schema. Unlike User Schema operations, Group Schema operations all specify default and don't accept a Schema ID.


Note: Since POST is interpreted as a partial update, you must set properties explicitly to null to remove them from the Schema.


Request 
Request Body schema: application/json
object (GroupSchemaDefinitions) 
 
object (GroupSchemaBase) 
 
object
The #base object properties


 
object (GroupSchemaCustom) 
All custom Profile properties are defined in a Profile subschema with the resolution scope #custom


 
object
The #custom object properties


 
description
string
Description for the Schema


 
object (UserSchemaProperties) 
 
object (UserSchemaPropertiesProfile) 
 
Array of objects (UserSchemaPropertiesProfileItem) 
 
title
string
User-defined display name for the Schema


 
Responses 
200
successful operation


400
Bad Request


403
Forbidden


429
Too Many Requests


post/api/v1/meta/schemas/group/default
Request samples 
application/json
{
  • "definitions": {
    • "custom": {
      }
    }
}
Response samples 
application/json
{
  • "Response with a subset of properties for brevity": {
    • "$ref": "#/components/examples/GroupSchemaResponse"
    }
}
List the Log Stream Schemas
OAuth 2.0: okta.logStreams.read
Lists the Schema for all Log Stream types visible for this org


Responses 
200
successful operation


403
Forbidden


429
Too Many Requests


get/api/v1/meta/schemas/logStream
Request samples 
Response samples 
application/json
[
  • {
    • "$schema": "https://json-schema.org/draft/2020-12/schema",
    • "$id": "http://{yourOktaDomain}/api/v1/meta/schemas/logStream/aws_eventbridge",
    • "title": "AWS EventBridge",
    • "type": "object",
    • "properties": {
      },
    • "required": [
      ],
    • "errorMessage": {
      }
    },
  • {
    • "$schema": "https://json-schema.org/draft/2020-12/schema",
    • "id": "http://{yourOktaDomain}/api/v1/meta/schemas/logStream/splunk_cloud_logstreaming",
    • "title": "Splunk Cloud",
    • "type": "object",
    • "properties": {
      },
    • "required": [
      ],
    • "errorMessage": {
      }
    }
]
Retrieve the Log Stream Schema for the schema type
OAuth 2.0: okta.logStreams.read
Retrieves the Schema for a Log Stream type. The logStreamType element in the URL specifies the Log Stream type, which is either aws_eventbridge or splunk_cloud_logstreaming. Use the aws_eventbridge literal to retrieve the AWS EventBridge type schema, and use the splunk_cloud_logstreaming literal retrieve the Splunk Cloud type schema.


Request 
path Parameters
logStreamType
required
string (LogStreamType) 
Specifies the streaming provider used


Supported providers:



Select the provider type to see provider-specific configurations in the settings property:


 Enum: "aws_eventbridge" "splunk_cloud_logstreaming"  
Responses 
200
successful operation


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/meta/schemas/logStream/{logStreamType}
Request samples 
Response samples 
application/json
{
  • "$schema": "https://json-schema.org/draft/2020-12/schema",
  • "$id": "http://{yourOktaDomain}/api/v1/meta/schemas/logStream/aws_eventbridge",
  • "title": "AWS EventBridge",
  • "type": "object",
  • "properties": {
    • "settings": {
      },
    • "name": {
      }
    },
  • "required": [
    • "name",
    • "settings"
    ],
  • "errorMessage": {
    • "properties": {
      }
    }
}
Retrieve a User Schema
OAuth 2.0: okta.schemas.read
Retrieves the Schema for a User Type


Request 
path Parameters
schemaId
required
string
 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/meta/schemas/user/{schemaId}
Request samples 
Response samples 
application/json
{
  • "id": "https://{yourOktaDomain}/meta/schemas/user/default",
  • "$schema": "http://json-schema.org/draft-04/schema#",
  • "name": "user",
  • "title": "Default Okta User",
  • "lastUpdated": "2015-09-05T10:40:45.000Z",
  • "created": "2015-02-02T10:27:36.000Z",
  • "definitions": {
    • "base": {
      },
    • "custom": {
      }
    },
  • "type": "object",
  • "properties": {
    • "profile": {
      }
    }
}
Update a User Schema
OAuth 2.0: okta.schemas.manage
Updates a User Schema. This updates, adds, or removes one or more profile properties in a User Schema. 


Unlike custom User Profile properties, limited changes are allowed to base User Profile properties (permissions, nullability of the firstName and lastName properties, or pattern for login). A property cannot be removed from the default Schema if it is being referenced as a matchAttribute in SAML2 IdPs. Currently, all validation of SAML assertions is only performed against the default user type.


Request 
path Parameters
schemaId
required
string
 
Request Body schema: application/json
required
object
User Profile subschemas


The Profile object for a User is defined by a composite Schema of base and custom properties using a JSON path to reference subschemas. The #base properties are defined and versioned by Okta, while #custom properties are extensible. Custom property names for the Profile object must be unique and can't conflict with a property name defined in the #base subschema.


 
object (UserSchemaBase) 
All Okta-defined Profile properties are defined in a Profile subschema with the resolution scope #base. You can't modify these properties, except to update permissions, to change the nullability of firstName and lastName, or to specify a pattern for login. They can't be removed.


The base User Profile is based on the System for Cross-domain Identity Management: Core Schema and has the standard properties detailed below.


 
object
The #base object properties


 
object (UserSchemaPublic) 
All custom Profile properties are defined in a Profile subschema with the resolution scope #custom


 
object
The #custom object properties


 
object
User Object Properties


 
object (UserSchemaPropertiesProfile) 
 
Array of objects (UserSchemaPropertiesProfileItem) 
 
title
string
User-defined display name for the Schema


 
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/meta/schemas/user/{schemaId}
Request samples 
application/json
{
  • "definitions": {
    • "custom": {
      }
    }
}
Response samples 
application/json
{
  • "id": "https://{yourOktaDomain}/meta/schemas/user/default",
  • "$schema": "http://json-schema.org/draft-04/schema#",
  • "name": "user",
  • "title": "Default Okta User",
  • "lastUpdated": "2015-09-05T10:40:45.000Z",
  • "created": "2015-02-02T10:27:36.000Z",
  • "definitions": {
    • "base": {
      },
    • "custom": {
      }
    },
  • "type": "object",
  • "properties": {
    • "profile": {
      }
    }
}