Mappings API

The Okta Mappings API provides operations to manage the mapping of properties between an Okta User's and an App User's Profile properties using Expression Language. More information on Okta User and App User Profiles can be found in Okta's Universal Directory.

Get started

Explore the Mappings API:

Profile Mapping operations

List Profile Mappings

GET /api/v1/mappings

Enumerates Profile Mappings in your organization with pagination. You can return a subset of Profile Mapping(s) that match a supported sourceId and/or targetId.

Request parameters

Parameter	Description	Param Type	DataType	Required	Default
after	Mapping `id` that specifies the pagination cursor for the next page of mappings	Query	String	FALSE	N/A
limit	Specifies the number of results per page (maximum 200)	Query	Number	FALSE	20
sourceId	UserType or App Instance `id` that acts as the source of expressions in a mapping. If included, all mappings returned have this as their `source:id`.	Query	String	FALSE	N/A
targetId	UserType or App Instance `id` that acts as the target of expressions in a mapping. If included, all mappings returned have this as their `target:id`.	Query	String	FALSE	N/A

The results are paginated according to the limit parameter. If there are multiple pages of results, the Link header contains a next link that should be treated as an opaque value (follow it, don't parse it).

Response parameters

Collection of Profile Mapping(s)

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/mappings?sourceId=${sourceId}"

Response example

[
    {
        "id": "prm1k47ghydIQOTBW0g4",
        "source": {
            "id": "${sourceId}",
            "name": "user",
            "type": "user",
            "_links": {
                "self": {
                    "href": "https://${yourOktaDomain}/api/v1/meta/types/user/otysbePhQ3yqt4cVv0g3"
                },
                "schema": {
                    "href": "https://${yourOktaDomain}/api/v1/meta/schemas/user/oscsbePhQ3yqt4cVv0g3"
                }
            }
        },
        "target": {
            "id": "0oa1xz9cb7yt5SsZV0g4",
            "name": "zendesk",
            "type": "appuser",
            "_links": {
                "self": {
                    "href": "https://${yourOktaDomain}/api/v1/apps/0oa1xz9cb7yt5SsZV0g4"
                },
                "schema": {
                    "href": "https://${yourOktaDomain}/api/v1/meta/schemas/apps/0oa1xz9cb7yt5SsZV0g4/default"
                }
            }
        },
        "_links": {
            "self": {
                "href": "https://${yourOktaDomain}/api/v1/mappings/prm1k47ghydIQOTBW0g4"
            }
        }
    },
    {
        "id": "prm1k48weFSOnEUnw0g4",
        "source": {
            "id": "${sourceId}",
            "name": "user",
            "type": "user",
            "_links": {
                "self": {
                    "href": "https://${yourOktaDomain}/api/v1/meta/types/user/otysbePhQ3yqt4cVv0g3"
                },
                "schema": {
                    "href": "https://${yourOktaDomain}/api/v1/meta/schemas/user/oscsbePhQ3yqt4cVv0g3"
                }
            }
        },
        "target": {
            "id": "0oa1ycesCAeQrbO3s0g4",
            "name": "sevenoffice",
            "type": "appuser",
            "_links": {
                "self": {
                    "href": "https://${yourOktaDomain}/api/v1/apps/0oa1ycesCAeQrbO3s0g4"
                },
                "schema": {
                    "href": "https://${yourOktaDomain}/api/v1/meta/schemas/apps/0oa1ycesCAeQrbO3s0g4/default"
                }
            }
        },
        "_links": {
            "self": {
                "href": "https://${yourOktaDomain}/api/v1/mappings/prm1k48weFSOnEUnw0g4"
            }
        }
    }
]

Get Profile Mapping

GET /api/v1/mappings/${mappingId}

Fetches a single Profile Mapping referenced by its ID

Request parameters

Parameter	Description	Param Type	DataType	Required	Default
mappingId	Unique identifier for Profile Mapping	URL	String	TRUE	N/A

Response parameters

Fetched Profile Mapping

Request example

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/mappings/${mappingId}"

Response example

{
    "id": "${mappingId}",
    "source": {
        "id": "otysbePhQ3yqt4cVv0g3",
        "name": "user",
        "type": "user",
        "_links": {
            "self": {
                "href": "https://${yourOktaDomain}/api/v1/meta/types/user/otysbePhQ3yqt4cVv0g3"
            },
            "schema": {
                "href": "https://${yourOktaDomain}/api/v1/meta/schemas/user/oscsbePhQ3yqt4cVv0g3"
            }
        }
    },
    "target": {
        "id": "0oa1qmn4LZQQEH0wZ0g4",
        "name": "okta_org2org",
        "type": "appuser",
        "_links": {
            "self": {
                "href": "https://${yourOktaDomain}/api/v1/apps/0oa1qmn4LZQQEH0wZ0g4"
            },
            "schema": {
                "href": "https://${yourOktaDomain}/api/v1/meta/schemas/apps/0oa1qmn4LZQQEH0wZ0g4/default"
            }
        }
    },
    "properties": {
        "firstName": {
            "expression": "user.firstName",
            "pushStatus": "PUSH"
        },
        "lastName": {
            "expression": "user.lastName",
            "pushStatus": "PUSH"
        }
    },
    "_links": {
        "self": {
            "href": "https://${yourOktaDomain}/api/v1/mappings/${mappingId}"
        }
    }
}

Update Profile Mapping

POST /api/v1/mappings/${mappingId}

Updates an existing Profile Mapping by adding, updating, or removing one or many Property Mappings

Add Property Mapping
Update Property Mapping
Remove Property Mapping

Request parameters

Parameter	Description	Param Type	DataType	Required	Default
mappingId	Unique identifier for Profile Mapping	URL	String	TRUE	N/A

Response parameters

All responses return the updated Profile Mapping

Add Property Mapping

Adds a Property Mapping to an existing Profile Mapping

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
    "properties": {
        "fullName": {
            "expression": "user.firstName + user.lastName",
            "pushStatus": "PUSH"
        },
        "nickName": {
            "expression": "user.nickName",
            "pushStatus": "PUSH"
        }
    }
}' "https://${yourOktaDomain}/api/v1/mappings/${mappingId}"

Response example

{
    "id": "${mappingId}",
    "source": {
        "id": "otysbePhQ3yqt4cVv0g3",
        "name": "user",
        "type": "user",
        "_links": {
            "self": {
                "href": "https://${yourOktaDomain}/api/v1/meta/types/user/otysbePhQ3yqt4cVv0g3"
            },
            "schema": {
                "href": "https://${yourOktaDomain}/api/v1/meta/schemas/user/oscsbePhQ3yqt4cVv0g3"
            }
        }
    },
    "target": {
        "id": "0oa1qmn4LZQQEH0wZ0g4",
        "name": "okta_org2org",
        "type": "appuser",
        "_links": {
            "self": {
                "href": "https://${yourOktaDomain}/api/v1/apps/0oa1qmn4LZQQEH0wZ0g4"
            },
            "schema": {
                "href": "https://${yourOktaDomain}/api/v1/meta/schemas/apps/0oa1qmn4LZQQEH0wZ0g4/default"
            }
        }
    },
    "properties": {
        "fullName": {
            "expression": "user.firstName + user.lastName",
            "pushStatus": "PUSH"
        },
        "nickName": {
            "expression": "user.nickName",
            "pushStatus": "PUSH"
        }
    },
    "_links": {
        "self": {
            "href": "https://${yourOktaDomain}/api/v1/mappings/${mappingId}"
        }
    }
}

Update Property Mapping

Alters an existing Property Mapping within a Profile Mapping

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
    "properties": {
        "nickName": {
            "expression": "user.honorificPrefix + user.displayName",
            "pushStatus": "DONT_PUSH"
        }
    }
}' "https://${yourOktaDomain}/api/v1/mappings/${mappingId}"

Response example

{
    "id": "${mappingId}",
    "source": {
        "id": "otysbePhQ3yqt4cVv0g3",
        "name": "user",
        "type": "user",
        "_links": {
            "self": {
                "href": "https://${yourOktaDomain}/api/v1/meta/types/user/otysbePhQ3yqt4cVv0g3"
            },
            "schema": {
                "href": "https://${yourOktaDomain}/api/v1/meta/schemas/user/oscsbePhQ3yqt4cVv0g3"
            }
        }
    },
    "target": {
        "id": "0oa1qmn4LZQQEH0wZ0g4",
        "name": "okta_org2org",
        "type": "appuser",
        "_links": {
            "self": {
                "href": "https://${yourOktaDomain}/api/v1/apps/0oa1qmn4LZQQEH0wZ0g4"
            },
            "schema": {
                "href": "https://${yourOktaDomain}/api/v1/meta/schemas/apps/0oa1qmn4LZQQEH0wZ0g4/default"
            }
        }
    },
    "properties": {
        "fullName": {
            "expression": "user.firstName + user.lastName",
            "pushStatus": "PUSH"
        },
        "nickName": {
            "expression": "user.honorificPrefix + user.displayName",
            "pushStatus": "DONT_PUSH"
        }
    },
    "_links": {
        "self": {
            "href": "https://${yourOktaDomain}/api/v1/mappings/${mappingId}"
        }
    }
}

Remove Property Mapping

Removes an existing Property Mapping within a Profile Mapping

Request example

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
    "properties": {
        "nickName": null
    }
}' "https://${yourOktaDomain}/api/v1/mappings/${mappingId}"

Response example

{
    "id": "${mappingId}",
    "source": {
        "id": "otysbePhQ3yqt4cVv0g3",
        "name": "user",
        "type": "user",
        "_links": {
            "self": {
                "href": "https://${yourOktaDomain}/api/v1/meta/types/user/otysbePhQ3yqt4cVv0g3"
            },
            "schema": {
                "href": "https://${yourOktaDomain}/api/v1/meta/schemas/user/oscsbePhQ3yqt4cVv0g3"
            }
        }
    },
    "target": {
        "id": "0oa1qmn4LZQQEH0wZ0g4",
        "name": "okta_org2org",
        "type": "appuser",
        "_links": {
            "self": {
                "href": "https://${yourOktaDomain}/api/v1/apps/0oa1qmn4LZQQEH0wZ0g4"
            },
            "schema": {
                "href": "https://${yourOktaDomain}/api/v1/meta/schemas/apps/0oa1qmn4LZQQEH0wZ0g4/default"
            }
        }
    },
    "properties": {
        "fullName": {
            "expression": "user.firstName + user.lastName",
            "pushStatus": "PUSH"
        }
    },
    "_links": {
        "self": {
            "href": "https://${yourOktaDomain}/api/v1/mappings/${mappingId}"
        }
    }
}

Profile Mapping object

The Profile Mapping object describes a mapping between an Okta User's and an App User's properties using JSON Schema Draft 4.

Note: Same type source/target mappings aren't supported by this API. Profile Mappings must either be Okta->App or App->Okta.

Example Profile Mapping

{
    "id": "prm1xzjkHwo8uG77c0g4",
    "source": {
        "id": "0oa1qmn4LZQQEH0wZ0g4",
        "name": "okta_org2org",
        "type": "appuser",
        "_links": {
            "self": {
                "href": "https://${yourOktaDomain}/api/v1/apps/0oa1qmn4LZQQEH0wZ0g4"
            },
            "schema": {
                "href": "https://${yourOktaDomain}/api/v1/meta/schemas/apps/0oa1qmn4LZQQEH0wZ0g4/default"
            }
        }
    },
    "target": {
        "id": "otysbePhQ3yqt4cVv0g3",
        "name": "user",
        "type": "user",
        "_links": {
            "self": {
                "href": "https://${yourOktaDomain}/api/v1/meta/types/user/otysbePhQ3yqt4cVv0g3"
            },
            "schema": {
                "href": "https://${yourOktaDomain}/api/v1/meta/schemas/user/oscsbePhQ3yqt4cVv0g3"
            }
        }
    },
    "properties": {
        "fullName": {
            "expression": "appuser.firstName + appuser.lastName",
            "pushStatus": "PUSH"
        },
        "nickName": {
            "expression": "appuser.nickName",
            "pushStatus": "DONT_PUSH"
        }
    },
    "_links": {
        "self": {
            "href": "https://${yourOktaDomain}/api/v1/mappings/prm1xzjkHwo8uG77c0g4"
        }
    }
}

Profile Mapping properties

The Profile Mapping is a valid JSON Schema Draft 4 document with the following properties:

Property	Description	DataType	Nullable	Unique	Readonly
_links	Discoverable resources related to the Profile Mapping	JSON HAL	FALSE	FALSE	TRUE
id	Unique identifier for Profile Mapping	String	FALSE	TRUE	TRUE
properties	Profile Mapping properties	Collection of Property Mappings	TRUE	FALSE	FALSE
source	Source of schema property expressions	AppInstance object or Okta object	FALSE	FALSE	TRUE
target	Target of schema property expressions	AppInstance object or Okta object	FALSE	FALSE	TRUE

AppInstance Attribute object

Can be either the source or target of a Profile Mapping and is a valid JSON Schema Draft 4 document with the following properties:

Property	Description	DataType	Nullable	Unique	Read-Only
_links	Discoverable resources related to the application instance	JSON HAL	FALSE	FALSE	TRUE
id	Unique identifier for application instance	String	FALSE	TRUE	TRUE
name	Variable name of the application instance	String	FALSE	TRUE	TRUE
type	Type of user referenced in mapping	String	FALSE	FALSE	TRUE

Okta Attribute object

Can be either the source or target of a Profile Mapping and is a valid JSON Schema Draft 4 document with the following properties:

Property	Description	DataType	Nullable	Unique	Readonly
_links	Discoverable resources related to the userType	JSON HAL	FALSE	FALSE	TRUE
id	Unique identifier for userType	String	FALSE	TRUE	TRUE
name	Name of the userType being referenced	String	FALSE	TRUE	TRUE
type	Type of user referenced in mapping	String	FALSE	FALSE	TRUE

Note: If the source/target is Okta and the UserTypes feature isn't enabled, then the source/target _links only has a link to the schema.

Property Mapping object

Consists of a target property, in String form, that maps to a valid JSON Schema Draft 4 document with the following properties:

Property	Description	DataType	Nullable	Unique	Readonly	Validation
expression	Combination or single source properties that are mapped to the target property	Expression Language object	FALSE	FALSE	FALSE
pushStatus	Indicates whether to update target properties on user create and update or just on create	`DONT_PUSH` or `PUSH`	FALSE	FALSE	FALSE

Note: Having a pushStatus of PUSH causes properties in the target to be updated on create and update. Having a pushStatus of DONT_PUSH causes properties in the target to be updated only on create.

On This Page

Mappings API

Get started

Profile Mapping operations

List Profile Mappings

Request parameters

Response parameters

Request example

Response example

Get Profile Mapping

Request parameters

Response parameters

Request example

Response example

Update Profile Mapping

Request parameters

Response parameters

Add Property Mapping

Request example

Response example

Update Property Mapping

Request example

Response example

Remove Property Mapping

Request example

Response example

Profile Mapping object

Example Profile Mapping

Profile Mapping properties

AppInstance Attribute object

Okta Attribute object

Property Mapping object