User Types API

The User Types API provides operations to manage User Types. See the User Schema API reference (opens new window).

Note: Some of the curl code examples on this page include SSWS API token authentication. However, Okta recommends using scoped OAuth 2.0 and OIDC access tokens to authenticate with Okta management APIs. OAuth 2.0 and OIDC access tokens provide fine-grain control over the bearer's actions on specific endpoints. See Okta API authentication methods.

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

Parameter	Description	Param Type	DataType	Required
displayName	The display name for the type	Body	string	TRUE
name	The name for the type. The name must start with A-Z or a-z and contain only A-Z, a-z, 0-9, or underscore (_) characters. This value becomes read-only after creation and can't be updated.	Body	string	TRUE
description	A human-readable description of the type	Body	string	FALSE

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"
    }
  }
}

Replace User Type

PUT /api/v1/meta/types/user/${typeId}

Replaces an existing User Type. A PUT is a full replace operation. 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 Update a User Schema endpoint (opens new window).

Request parameters

Parameter	Description	Param Type	DataType	Required
typeId	The ID of the user type you want to replace	Path	string	TRUE
displayName	The new display name for the type	Body	string	TRUE
name	The name of the existing type	Body	string	TRUE
description	The new human-readable description of the type	Body	string	TRUE

Response parameters

The updated User Types

Request example

curl -s -X PUT -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": "existingTypeName"
}'

Response example

{
  "id": "otyfnly5cQjJT9PnR0g4",
  "displayName": "Updated Name for UI",
  "name": "existingTypeName",
  "description": "Updated description",
  "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

POST /api/v1/meta/types/user/${typeId}

Updates an existing User Type. 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 Update a User Schema endpoint (opens new window).

Request parameters

Parameter	Description	Param Type	DataType	Required
typeId	The ID of the user type you want to update	Path	string	TRUE
displayName	The new display name for the type	Body	string	FALSE
description	The new human-readable description of the type	Body	string	FALSE

Response parameters

The updated User Types

Request example

curl -s -X POST -H "Content-Type: application/json" -H "Authorization: SSWS ${api_token}" https://${yourOktaDomain}/api/v1/meta/types/user/otyfnly5cQjJT9PnR0g4 -d '{
"displayName": "Updated Name for UI"
}'

Response example

{
  "id": "otyfnly5cQjJT9PnR0g4",
  "displayName": "Updated Name for UI",
  "name": "existingTypeName",
  "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