See api-docs Menu

User Mappings

The User Mappings API can be used to list, create, update, re-order, and delete user mappings.

Mappings in OneLogin enable you to automate changes to user attributes, roles, and groups, based on conditions that you define. Typically, you use mappings to grant application access based on user attributes stored in third-party directories.

Mappings will not be automatically applied when they modified via this API.

Either a User must be created/updated or “Reapply Mappings” must be run via UI to trigger the application of mappings.

Parts of a mapping

A mapping is similar to an “if this then that” concept where the “this” is a condition and the “that” is the action to take.

Depending on the setting of the match attribute, one or more conditions must be met in order for the mapping action(s) to be applied.


A condition is an object that consists of a source, an operator, and a value.

    "source": "member_of",
    "operator": "~",
    "value": "SECURITY-GROUP-1"

The list of possible condition sources is available using the list conditions endpoint. The list of possible operators changes with the condition that is selected. The same is true for the list of condition values.

When no condition values are returned this indicates that free text is accepted.


An action is an object that consists of a action, and a value.

    "action": "add_role",
    "value": "272444"

Similar to conditions, all possible actions can be retrieved using the list actions endpoint. The list of possible values changes based on the action that is selected.

When no actions values are returned this indicates that free text is accepted.

Create a mapping

For example, you can create a mapping to assign a OneLogin role (and access to all of the apps defined by that role) to users whose memberOf attribute contains a specified Active Directory security group.

curl 'https://<subdomain>/api/2/mappings' \
-H "Authorization: bearer <access_token>"
-H "Content-Type: application/json" \
-d '{
    "name": "Assign a role",
    "match": "all",
    "enabled": true,
    "position": null,
    "conditions": [
            "source": "member_of",
            "operator": "~",
            "value": "SECURITY-GROUP-1"
    "actions": [
            "action": "add_role",
            "value": "272444"

Postman Collection

Replace sample variables indicated by {{ }} with your actual values.

Run in Postman

    Clicking Run in Postman button navigates to the page where you can fork the collection to your workspace. Forking the collection into your workspace will enable you to contribute to the source collection using pull requests. You can also view the collection in a public workspace if you like and even import a copy of the collection using the links present on the screen.


div class=”callout callout-info”>

Have a Question?

Have a Question?

Found a problem or a bug? Submit a support ticket.

Looking for walkthroughs or how-to guides on OneLogin's user and admin features? Check out the documentation in our Knowledge Base.

Have a product idea or request? Share it with us in our Ideas Portal.