On this page
User Types API
The User Types API provides operations to manage User Types. See the User Schema API reference for information on managing the schemas associated with the User Types.
Get started
Explore the User Types API: (opens new window)
User Types operations
Get all User Types
GET /api/v1/meta/types/user
Fetches all the User Types in your org
Request parameters
None
Response parameters
An array of fetched User Types
Request example
curl -s -H "Authorization: SSWS ${api_token}" https://${yourOktaDomain}/api/v1/meta/types/user
Response example
[
{
"id": "otyfnly5cQjJT9PnR0g4",
"displayName": "Nootype",
"name": "newtype",
"description": "Custom user type",
"createdBy": "00ufnlhzppWItClAI0g4",
"lastUpdatedBy": "00ufnlhzppWItClAI0g4",
"created": "2019-04-10T02:00:01.000Z",
"lastUpdated": "2019-04-10T02:00:01.000Z",
"default": false,
"_links": {
"schema": {
"rel": "schema",
"href": "https://{yourOktaDomain}/api/v1/meta/schemas/user/oscfnly5cQjJT9PnR0g4",
"method": "GET"
},
"self": {
"rel": "self",
"href": "https://{yourOktaDomain}/api/v1/meta/types/user/otyfnly5cQjJT9PnR0g4",
"method": "GET"
}
}
},
{
"id": "otyfnjfba4ye7pgjB0g4",
"displayName": "User",
"name": "user",
"description": "Okta user profile template with default permission settings",
"createdBy": "00ufnlhzppWItClAI0g4",
"lastUpdatedBy": "00ufnlhzppWItClAI0g4",
"created": "2019-04-10T01:48:27.000Z",
"lastUpdated": "2019-04-10T01:48:27.000Z",
"default": true,
"_links": {
"schema": {
"rel": "schema",
"href": "https://{yourOktaDomain}/api/v1/meta/schemas/user/oscfnjfba4ye7pgjB0g4",
"method": "GET"
},
"self": {
"rel": "self",
"href": "https://{yourOktaDomain}/api/v1/meta/types/user/otyfnjfba4ye7pgjB0g4",
"method": "GET"
}
}
}
]
Get User Type (by ID or default)
GET /api/v1/meta/types/user/${typeId}
Fetches a User Type by ID. Use the special identifier default
to fetch the default User Type.
Request Parameters
None
Response parameters
The fetched User Type
Request Example
curl -s -H "Authorization: SSWS ${api_token}" https://${yourOktaDomain}/api/v1/meta/types/user/${typeId}
Response Example
{
"id": "otyfnly5cQjJT9PnR0g4",
"displayName": "Nootype",
"name": "newtype",
"description": "Custom user type",
"createdBy": "00ufnlhzppWItClAI0g4",
"lastUpdatedBy": "00ufnlhzppWItClAI0g4",
"created": "2019-04-10T02:00:01.000Z",
"lastUpdated": "2019-04-10T02:00:01.000Z",
"default": false,
"_links": {
"schema": {
"rel": "schema",
"href": "https://{yourOktaDomain}/api/v1/meta/schemas/user/oscfnly5cQjJT9PnR0g4",
"method": "GET"
},
"self": {
"rel": "self",
"href": "https://{yourOktaDomain}/api/v1/meta/types/user/otyfnly5cQjJT9PnR0g4",
"method": "GET"
}
}
}
Create User Type
POST /api/v1/meta/types/user/
Creates a new User Type. A default
User Type is automatically created with your org, and you can add another nine User Types for a maximum of 10.
Okta periodically updates the default schema template used for new orgs. New User Types are based on the most up-to-date template. This means the properties that a new User Type is initialized with aren't necessarily the same properties that your default type received.
Note: If you modified your default schema, those changes won't propagate into this new User Type.
Request Parameters
The User Type you want to create
Response parameters
The created User Type
Request example
curl -s -XPOST -H "Content-Type: application/json" -H "Authorization: SSWS ${api_token}" https://${yourOktaDomain}/api/v1/meta/types/user -d '{
"description": "Any description that means something useful to you",
"displayName": "Display Name for UI",
"name": "aNewType"
}'
Response example
{
"id": "otyfnly5cQjJT9PnR0g4",
"displayName": "Display Name for UI",
"name": "aNewType",
"description": "Any description that means something useful to you",
"createdBy": "00ufnlhzppWItClAI0g4",
"lastUpdatedBy": "00ufnlhzppWItClAI0g4",
"created": "2019-04-10T02:00:01.000Z",
"lastUpdated": "2019-04-10T02:00:01.000Z",
"default": false,
"_links": {
"schema": {
"rel": "schema",
"href": "https://{yourOktaDomain}/api/v1/meta/schemas/user/oscfnly5cQjJT9PnR0g4",
"method": "GET"
},
"self": {
"rel": "self",
"href": "https://{yourOktaDomain}/api/v1/meta/types/user/otyfnly5cQjJT9PnR0g4",
"method": "GET"
}
}
}
Update User Type
PUT /api/v1/meta/types/user/${typeId}
POST /api/v1/meta/types/user/${typeId}
Updates an existing User Type. A PUT is a full replace operation; a POST is a partial update. Only the displayName
and description
elements can be changed; the name
of an existing User Type can't be changed.
The schema associated with this type isn't editable with this API. If you want to edit the schema, use the schema update API.
Request parameters
The User Type you want to update
Response parameters
The updated User Types
Request example
curl -s -XPUT -H "Content-Type: application/json" -H "Authorization: SSWS ${api_token}" https://${yourOktaDomain}/api/v1/meta/types/user/otyfnly5cQjJT9PnR0g4 -d '{
"description": "Updated description",
"displayName": "Updated Name for UI",
"name": "updatedTypeName"
}'
Response example
{
"id": "otyfnly5cQjJT9PnR0g4",
"displayName": "TheDisplayName",
"name": "aNewType",
"description": "Any description that means something useful to you",
"createdBy": "00ufnlhzppWItClAI0g4",
"lastUpdatedBy": "00ufnlhzppWItClAI0g4",
"created": "2019-04-10T02:00:01.000Z",
"lastUpdated": "2019-04-10T02:00:01.000Z",
"default": false,
"_links": {
"schema": {
"rel": "schema",
"href": "https://{yourOktaDomain}/api/v1/meta/schemas/user/oscfnly5cQjJT9PnR0g4",
"method": "GET"
},
"self": {
"rel": "self",
"href": "https://{yourOktaDomain}/api/v1/meta/types/user/otyfnly5cQjJT9PnR0g4",
"method": "GET"
}
}
}
Delete User Type
DELETE /api/v1/meta/types/user/${typeId}
Deletes a User Type permanently. This operation isn't permitted for the default type or for any User Type that has existing users. After you delete a User Type, it can't be used as the type for new users, and it no longer counts against the limit of 10 User Types.
Request parameters
Parameter | Description | Param Type | DataType | Required | Default |
---|---|---|---|---|---|
typeId | id of the User Type | URL | String | TRUE |
Response parameters
None.
Passing an invalid typeId
returns a 404 Not Found
status code with error code E0000007
.
Passing the ID of the default type returns a 403 Forbidden
status code with error code E0000142
and a reason
of PROHIBITED
.
Passing the ID of a type for which non-deleted users exist returns a 403 Forbidden
status code with error code E0000142
and a reason
of UNMET_REQUIREMENTS
.
Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/meta/types/user/otyfnly5cQjJT9PnR0g4"
Response example
HTTP/1.1 204 No Content
Specify the User Type of a new user
The Create User operation accepts a type specification as part of the request body. The specification is a map, but currently the only key permitted is id
. The type specification is also added to the User object, but after user creation, only an administrator can update the type by doing a full replace of an existing user, not a partial update.
Example
"type": {
"id": "otyfnjfba4ye7pgjB0g4"
}
User Type object
Example User Type
{
"id": "otyfnly5cQjJT9PnR0g4",
"displayName": "Freelancer",
"name": "Freelance Contractors",
"description": "The road goes ever on and on",
"createdBy": "00ubade0d00f1f73b234",
"lastUpdatedBy": "00ubade0d00f1f73b234",
"default": false,
"created": "2013-07-02T21:36:25.344Z",
"lastUpdated": "2013-07-02T21:36:25.344Z",
"_links": {
"schema": {
"rel": "schema",
"href": "https://{yourOktaDomain}/api/v1/meta/schemas/user/oscfnly5cQjJT9PnR0g4",
"method": "GET"
},
"self": {
"rel": "schema",
"href": "https://{yourOktaDomain}/api/v1/meta/types/user/otyfnly5cQjJT9PnR0g4",
"method": "GET"
}
}
}
User Type Properties
The User Type object defines several properties:
Property | Description | DataType | Nullable | Unique | Readonly |
---|---|---|---|---|---|
id | Unique key for the User Type | String | FALSE | TRUE | TRUE |
displayName | The display name for the type | String | FALSE | FALSE | FALSE |
name | The name for the type | String | FALSE | TRUE | TRUE |
description | A human-readable description of the type | String | FALSE | FALSE | FALSE |
createdBy | The user ID of the creator of this type | String | FALSE | FALSE | TRUE |
lastUpdatedBy | The user ID of the last user to edit this type | String | FALSE | FALSE | TRUE |
default | Boolean to indicate if this type is the default | Boolean | FALSE | FALSE | TRUE |
created | Timestamp when the User Type was created | String (ISO-8601) | FALSE | FALSE | TRUE |
lastUpdated | Timestamp when the User Type was last updated | String (ISO-8601) | FALSE | FALSE | TRUE |
_links | Link relations for the User Type | JSON HAL (opens new window) | TRUE | FALSE | TRUE |