Home >
API >
1 >
Users >
Set User State

Set User State

Set the State for a user.

States describe a stage in a process (such as user account approval). User state determines the possible statuses a user account can be in.

States, and their IDs, include:

Unapproved: 0
Approved (licensed): 1
Rejected: 2
Unlicensed: 3

For more information, see Introduction to User Management in the administrative Help Center.

Instead of this API, you can use the Update User by ID API to update a user’s state, except if a user is in the Unlicensed state (id=3) and you want to change their state. In that case, you must use the Set User State API.

Resource URL

https://<subdomain>/api/1/users/:id/set_state

Header Parameters

Authorization

required

string

Set to bearer:<access_token>.

Set <access_token> to the access token you generated using the Generate Token API.

The access token must have been generated using an API credential pair created using the scope required to call this API. This API can be called using the Manage All scope.

Content-Type

required

string

Set to application/json.

Resource Parameter

required

string

Set to the id of the user whose state you want to update. If you don’t know the user’s id, use the Get Users API call to return all users and their id values.

Request Parameter

state

required

integer

Set to the state value. Valid values include:

Unapproved: 0
Approved (licensed): 1
Rejected: 2
Unlicensed: 3

Sample Request Body

{
   "state":1
}

Sample Response

200 OK
400 Bad Req.
401 Unauth.
403 Forbid.
404 Not Found

{
    "status": {
        "type": "success",
        "code": 200,
        "message": "Success",
        "error": false
    }
}

Here are a few different errors that will return a 400 Bad Request status code.

{
    "status": {
        "error": true,
        "code": 400,
        "type": "bad request",
        "message": "user is already in this state"
    }
}

{
    "status": {
        "error": true,
        "code": 400,
        "type": "bad request",
        "message": {
            "description": "state has incorrect data type. It should be -> integer",
            "attribute": "state"
        }
    }
}

The following error means that the state change you are attempting is not valid for a user in their current state (attempting to update from Unlicensed to Unapproved, for example).

{
    "status": {
        "error": true,
        "code": 400,
        "type": "bad request",
        "message": "state is invalid"
    }
}

Aside from more obvious JSON formatting errors, the following error may also mean that your input JSON contains non-integers.

{
    "status": {
        "error": true,
        "code": 400,
        "type": "bad request",
        "message": "Input JSON is not valid"
    }
}

Typically, the following error means that the Authorization header is missing or incorrectly formatted. The Authorization header should use this format: bearer:<access_token>.

{
    "status": {
        "error": true,
        "code": 400,
        "type": "bad request",
        "message": "Authorization Information is incorrect"
 }
}

{
    "status": {
        "error": true,
        "code": 400,
        "type": "bad request",
        "message": "Content Type is not specified or specified incorrectly.
                    Content-Type header must be set to application/json"
    }
}

Typically, this error means that the access token is invalid.

{
  "status": {
    "error": true,
    "code": 401,
    "type": "Unauthorized",
    "message": "Authentication Failure"
 }
}

Typically, the following error means that the access token used to make the call was generated using API credentials that have insufficient permissions. This API can be called using the Manage All scope only.

{
    "status": {
        "error": true,
        "code": 401,
        "type": "Unauthorized",
        "message": "Insufficient Permission"
    }
}

{
    "status": {
        "error": true,
        "code": 403,
        "type": "forbidden",
        "message": "user is not authorized to access this User"
 }
}

{
    "status": {
        "error": true,
        "code": 404,
        "type": "not found",
        "message": "User for id 11111111 was not found"
 }
}

Postman Collection

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.

Sample Code

cURL

Replace sample values indicated by < > with your actual values.

curl 'https://<subdomain>/api/1/users/<id>/set_state' \
-X PUT \
-H "Authorization: bearer: <access_token>" \
-H "Content-Type: application/json" \
-d '{
    "state":<1>
}'

Python

See Work with OAuth 2.0 Tokens, Users, and Roles.

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.