OneLogin API v1 — user unlock and role assignment

This reference is readable without JavaScript. Download the OpenAPI document.

Runtime

/api/purple-suite/{instanceId}/contracts/identity/onelogin
[
  {
    "method": "get",
    "path": "/api/1/users/:id",
    "operationId": "getUserById"
  },
  {
    "method": "put",
    "path": "/api/1/users/:id",
    "operationId": "updateUser"
  },
  {
    "method": "put",
    "path": "/api/1/users/:id/add_roles",
    "operationId": "addRolesForUser"
  },
  {
    "method": "get",
    "path": "/api/1/users/:id/roles",
    "operationId": "getRolesForUser"
  }
]

Credentials

Coverage and limitations

{
  "documentScope": "bounded",
  "runtimeFidelity": "modeled",
  "counts": {
    "operations": 4
  },
  "notes": [
    "Exactly the 4 v1 calls the Moveworks OneLogin natives make: get user and update user (unlock is the only OneLogin account native; reset and change password raise NotImplementedError client-side), and add roles and get roles (remove-from-role and users-by-role also raise NotImplementedError).",
    "No token endpoint is served: the real connector's token call is hard-coded to api.us.onelogin.com, and the eval connector swap replaces the whole connector.",
    "Email lookup on getUserById is modeled: the v1 docs describe a numeric id, but the default roster mapper sends the email.",
    "Ids are strict integers. The contract knows the roster-seeded users and roles and the rows an eval imports; imported rows win in either order, and nothing creates a user or role.",
    "Roster users in departments beyond the first four (sorted) hold only the Default role.",
    "add_roles and update-user 400 texts follow the pinned doc pages, not the feature plan: an unknown role is 400 'role_id_array should be a subset of -> [<account role ids>]', not a 404; empty, wrong-type and non-integer arrays, a malformed id, an excluded id attribute, an invalid attribute and a wrong status type use the documented messages, including the object form.",
    "updateUser serves status and state only; any other attribute is refused as not a valid attribute (a narrowing). A status outside the documented 0-5, 7 and 8, the 429 for a locked-out key and the 500 are modeled texts.",
    "The 401 body is the recorded bare `{status:{error:true,code:401}}`, not the doc pages' longer form.",
    "People come from the shared PurpleSuite identity roster, joined on email."
  ]
}

Hand-written from OneLogin's v1 reference pages and its official Postman collection; OneLogin publishes no OpenAPI for these calls.

Servers

[
  {
    "url": "/api/purple-suite/{instanceId}/contracts/identity/onelogin"
  }
]

Authentication schemes

{
  "bearerAuth": {
    "type": "http",
    "scheme": "bearer"
  }
}

Each operation lists its security requirements. An empty security array permits an unauthenticated request. Use the scheme and headers declared for the selected contract.

Operations

GET /api/1/users/{id}

Get User by ID

Returns the user. The `id` is the user's integer id or, modeled, the user's email, which the default roster mapper sends. See https://developers.onelogin.com/api-docs/1/users/get-user-by-id/.

Authentication

[
  {
    "bearerAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "getUserById",
  "tags": [
    "Users"
  ],
  "summary": "Get User by ID",
  "description": "Returns the user. The `id` is the user's integer id or, modeled, the user's email, which the default roster mapper sends. See https://developers.onelogin.com/api-docs/1/users/get-user-by-id/.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "The user's integer id, or (modeled) the user's email, matched case-insensitively.",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UserEnvelope"
          }
        }
      }
    },
    "401": {
      "description": "Missing or invalid bearer token",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "Unknown user or instance",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "description": "Instance key locked out (modeled)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "500": {
      "description": "Internal error (modeled)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

PUT /api/1/users/{id}

Update User by ID

Updates the user's status or state. Status 1 also clears locked_until and invalid_login_attempts, as an unlock does. Other user attributes are not served. See https://developers.onelogin.com/api-docs/1/users/update-user/.

Authentication

[
  {
    "bearerAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "updateUser",
  "tags": [
    "Users"
  ],
  "summary": "Update User by ID",
  "description": "Updates the user's status or state. Status 1 also clears locked_until and invalid_login_attempts, as an unlock does. Other user attributes are not served. See https://developers.onelogin.com/api-docs/1/users/update-user/.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "The user's integer id.",
      "schema": {
        "type": "integer"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UpdateUserRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/UserEnvelope"
          }
        }
      }
    },
    "400": {
      "description": "Invalid body",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "Missing or invalid bearer token",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "Unknown user or instance",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "description": "Instance key locked out (modeled)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "500": {
      "description": "Internal error (modeled)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

PUT /api/1/users/{id}/add_roles

Assign Role to User

Adds the roles to the user. A role the user already holds, an unknown role, an empty array or a non-integer entry is a 400. See https://developers.onelogin.com/api-docs/1/users/assign-role-to-user/.

Authentication

[
  {
    "bearerAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "addRolesForUser",
  "tags": [
    "Users"
  ],
  "summary": "Assign Role to User",
  "description": "Adds the roles to the user. A role the user already holds, an unknown role, an empty array or a non-integer entry is a 400. See https://developers.onelogin.com/api-docs/1/users/assign-role-to-user/.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "The user's integer id.",
      "schema": {
        "type": "integer"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AddRolesRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/StatusEnvelope"
          }
        }
      }
    },
    "400": {
      "description": "Invalid body or id",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "Missing or invalid bearer token",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "Unknown user or instance",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "description": "Instance key locked out (modeled)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "500": {
      "description": "Internal error (modeled)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

GET /api/1/users/{id}/roles

Get Roles for a User

Returns the user's role ids as `data: [[...]]`. See https://developers.onelogin.com/api-docs/1/users/get-roles-for-user/.

Authentication

[
  {
    "bearerAuth": []
  }
]

Request, responses and operation details

{
  "operationId": "getRolesForUser",
  "tags": [
    "Users"
  ],
  "summary": "Get Roles for a User",
  "description": "Returns the user's role ids as `data: [[...]]`. See https://developers.onelogin.com/api-docs/1/users/get-roles-for-user/.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "The user's integer id.",
      "schema": {
        "type": "integer"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/RolesEnvelope"
          }
        }
      }
    },
    "401": {
      "description": "Missing or invalid bearer token",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "Unknown user or instance",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "description": "Instance key locked out (modeled)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "500": {
      "description": "Internal error (modeled)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}

Schemas and reusable components

securitySchemes

bearerAuth

{
  "type": "http",
  "scheme": "bearer"
}

schemas

Status

{
  "type": "object",
  "required": [
    "error",
    "code"
  ],
  "properties": {
    "error": {
      "type": "boolean"
    },
    "code": {
      "type": "integer"
    },
    "type": {
      "type": "string"
    },
    "message": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "object",
          "required": [
            "attribute",
            "description"
          ],
          "properties": {
            "attribute": {
              "type": "string"
            },
            "description": {
              "type": "string"
            }
          }
        }
      ]
    }
  }
}

User

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "email": {
      "type": "string",
      "nullable": true
    },
    "username": {
      "type": "string",
      "nullable": true
    },
    "firstname": {
      "type": "string",
      "nullable": true
    },
    "lastname": {
      "type": "string",
      "nullable": true
    },
    "distinguished_name": {
      "type": "string",
      "nullable": true
    },
    "samaccountname": {
      "type": "string",
      "nullable": true
    },
    "userprincipalname": {
      "type": "string",
      "nullable": true
    },
    "member_of": {
      "type": "string",
      "nullable": true
    },
    "phone": {
      "type": "string",
      "nullable": true
    },
    "company": {
      "type": "string",
      "nullable": true
    },
    "department": {
      "type": "string",
      "nullable": true
    },
    "title": {
      "type": "string",
      "nullable": true
    },
    "status": {
      "type": "integer",
      "nullable": true,
      "description": "0 unactivated, 1 active, 2 suspended, 3 locked, 4 password expired, 5 awaiting password reset, 7 password pending, 8 security questions required."
    },
    "state": {
      "type": "integer",
      "nullable": true,
      "description": "0 unapproved, 1 approved, 2 rejected, 3 unlicensed."
    },
    "role_id": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "integer"
      }
    },
    "group_id": {
      "type": "integer",
      "nullable": true
    },
    "directory_id": {
      "type": "integer",
      "nullable": true
    },
    "external_id": {
      "type": "string",
      "nullable": true
    },
    "manager_ad_id": {
      "type": "string",
      "nullable": true
    },
    "manager_user_id": {
      "type": "integer",
      "nullable": true
    },
    "invalid_login_attempts": {
      "type": "integer",
      "nullable": true
    },
    "locked_until": {
      "type": "string",
      "nullable": true
    },
    "last_login": {
      "type": "string",
      "nullable": true
    },
    "activated_at": {
      "type": "string",
      "nullable": true
    },
    "created_at": {
      "type": "string",
      "nullable": true
    },
    "updated_at": {
      "type": "string",
      "nullable": true
    },
    "password_changed_at": {
      "type": "string",
      "nullable": true
    },
    "invitation_sent_at": {
      "type": "string",
      "nullable": true
    },
    "locale_code": {
      "type": "string",
      "nullable": true
    },
    "openid_name": {
      "type": "string",
      "nullable": true
    },
    "notes": {
      "type": "string",
      "nullable": true
    },
    "trusted_idp_id": {
      "type": "integer",
      "nullable": true
    },
    "custom_attributes": {
      "type": "object",
      "nullable": true,
      "additionalProperties": true
    }
  }
}

UserEnvelope

{
  "type": "object",
  "required": [
    "status",
    "data"
  ],
  "properties": {
    "status": {
      "$ref": "#/components/schemas/Status"
    },
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/User"
      }
    }
  }
}

RolesEnvelope

{
  "type": "object",
  "required": [
    "status",
    "data"
  ],
  "properties": {
    "status": {
      "$ref": "#/components/schemas/Status"
    },
    "data": {
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "type": "integer"
        }
      }
    }
  }
}

StatusEnvelope

{
  "type": "object",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "$ref": "#/components/schemas/Status"
    }
  }
}

Error

{
  "type": "object",
  "required": [
    "status"
  ],
  "additionalProperties": false,
  "properties": {
    "status": {
      "$ref": "#/components/schemas/Status"
    }
  }
}

UpdateUserRequest

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "status": {
      "type": "integer",
      "enum": [
        0,
        1,
        2,
        3,
        4,
        5,
        7,
        8
      ]
    },
    "state": {
      "type": "integer",
      "minimum": 0,
      "maximum": 3
    }
  }
}

AddRolesRequest

{
  "type": "object",
  "required": [
    "role_id_array"
  ],
  "properties": {
    "role_id_array": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "integer"
      }
    }
  }
}

Document metadata and extensions

{
  "openapi": "3.0.3",
  "info": {
    "title": "OneLogin API v1 (users and roles)",
    "version": "1",
    "description": "Hand-written from OneLogin's v1 reference pages and its official Postman collection; OneLogin publishes no OpenAPI for these calls."
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Users"
    }
  ]
}
Interactive API explorer (requires JavaScript)