Actioning Users

1. Overview

This page contains the APIs that are used for actioning users. Once you have created the User Actions, you use this API to invoke a User Action on a User.

2. Take an Action on a User

This API is used to take a User Action on a User. User Actions are the method that FusionAuth uses to discipline, reward and interact with Users.

2.1. Request

Take an action on a User

URI

POST /api/user/action

Table 1. Request Body

action.actioneeUserId [UUID] Required

The Id of the User that is being actioned.

action.actionerUserId [UUID] Required

The Id of the User that is taking the action on the User.

action.applicationIds [Array<UUID>] Optional

The list of Application ids that the action is being performed in.

action.comment [String] Optional

The comment left by the actioner.

action.emailUser [Boolean] Optional defaults to false

Whether FusionAuth should send an email to the User.

action.expiry [Long] Optional

The expiration instant of this User Action. This value is required for time-based User Actions.

To cause the action to be applied indefinitely, or until the action is canceled or modified, set this value to 9223372036854775807.

action.notifyUser [Boolean] Optional defaults to false

The notifyUser flag that is passed along in any events FusionAuth sends to registered Webhooks.

action.option [String] Optional

The User Action Option that the actioner selected.

action.reasonId [UUID] Optional

The Id of the User Action Reason that the actioner selected.

action.userActionId [UUID] Required

The Id of the User Action that the actioner is performing on the User.

broadcast [Boolean] Optional defaults to false

Whether or not FusionAuth will broadcast the User Action to any registered Webhooks.

Example Request JSON
{
  "broadcast": true,
  "action": {
    "actioneeUserId": "00000000-0000-0000-0000-000000000001",
    "actionerUserId": "00000000-0000-0000-0000-000000000002",
    "comment": "This user is being a jerk",
    "emailUser": true,
    "expiry": 1471586483322,
    "notifyUser": true,
    "reasonId": "00000000-0000-0000-0000-000000000020",
    "userActionId": "00000000-0000-0000-0000-000000000011"
  }
}

2.2. Response

The response for this API contains the User Action along with any event and email information that was generated by FusionAuth.

Table 2. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

500

There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

503

The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

504

One or more Webhook endpoints returned an invalid response or were unreachable. Based on the transaction configuration for this event your action cannot be completed. A stack trace is provided and logged in the FusionAuth log files.

Table 3. Response Body for a single User Action Log

action.actioneeUserId [UUID]

The Id of the User that was actioned.

action.actionerUserId [UUID]

The Id of the User that took the action on the User. If the action was initiated by FusionAuth this value will not be provided.

action.applicationIds [Array<UUID>]

This parameter if provided specifies the scope of the User Action. When an Action is scoped to one or more Applications the Application Ids will be provided in this parameter.

action.comment [String]

An optional comment provided when the Action was created, updated or canceled. This value will always be the last comment set on the action, see history for previous values.

action.createInstant [Long]

The instant that the User Action was taken.

action.emailUserOnEnd [Boolean]

Whether FusionAuth will email the User when a time-based User Actions expires.

action.endEventSent [Boolean]

Whether FusionAuth will send events when a time-based User Actions expires.

action.expiry [Long]

The expiration instant of the User Action.

action.id [UUID]

The Id of the User Action record.

action.localizedOption [String]

The localized version of the User Action Option that was selected by the actioner.

action.localizedReason [String]

The localized version of the User Action Reason that was selected by the actioner.

action.notifyUserOnEnd [String]

Whether or not FusionAuth will send events to registered Webhooks when a time-based User Action expires.

action.option [String]

The non-localized version of the User Action Option that was selected by the actioner.

action.reason [String]

The non-localized version of the User Action Reason that was selected by the actioner.

action.reasonCode [String]

The User Action Reason code that was selected by the actioner.

action.userActionId [UUID]

The unique Id of the User Action. This Id can be used to retrieve the User Action using the Retrieve a User Action API.

Example Response JSON for a Single User Action
{
  "action": {
    "actioneeUserId": "00000000-0000-0000-0000-000000000001",
    "actionerUserId": "00000000-0000-0000-0000-000000000002",
    "applicationIds": [
      "00000000-0000-0000-0000-000000000042",
      "00000000-0000-0000-0000-000000000043"
    ],
    "comment": "This user is being a jerk",
    "createInstant": 1471786483322,
    "emailUserOnEnd": false,
    "endEventSent": false,
    "expiry": 1471586483322,
    "id": "00000000-0000-0000-0000-013500000002",
    "localizedOption": "Lock account full",
    "localizedReason": "Community rules infraction",
    "event": {
      "action": "Lock account full",
      "actionId": "00000000-0000-0000-0000-000000000010",
      "actioneeUserId": "00000000-0000-0000-0000-000000000001",
      "actionerUserId": "00000000-0000-0000-0000-000000000002",
      "comment": "This user is being a jerk",
      "createInstant": 1471786483322,
      "email": {
        "from": {
          "address": "support@fusionauth.io",
          "display": "FusionAuth Support"
        },
        "html": "...",
        "subject": "You account has been locked",
        "text": "...",
        "to": {
          "address": "foo@bar.com",
          "display": "Foo Jones"
        }
      },
      "expiry": 1471586483322,
      "localizedAction": "Lock account",
      "localizedOption": "Lock account full",
      "localizedReason": "Community rules infraction",
      "notifyUser": false,
      "option": "Lock account full",
      "emailedUser": false,
      "phase": "modify",
      "reason": "Community rules infraction",
      "reasonCode": "FRAC"
    },
    "notifyUserOnEnd": true,
    "option": "Lock account full",
    "reason": "Community rules infraction",
    "reasonCode": "FRAC",
    "userActionId": "00000000-0000-0000-0000-000000000010"
  }
}

3. Retrieve a Previously Taken Action

This API is used to retrieve a User Action that was previously taken on a User, this can be thought of as the log or historical record.

3.1. Request

Retrieve a specific User Action Log by Id.

URI

GET /api/user/action/{actionId}

Table 4. Request Parameters

actionId [UUID] Required

The unique Id of the Action to retrieve.

Retrieve all the Actions for a specific User by the User Id.

URI

GET /api/user/action/?userId={userId}

Table 5. Request Parameters

userId [UUID] Required

The unique Id of the User for which to retrieve all of the Actions.

3.2. Response

The response for this API contains either a single User Action Log or a list of User Actions Logs for a User. If you specified an actionId on the URI the response will contain the User Action Log for that Id. If you pass in a userId as a URL parameter the response will contain all of the User Action Logs for that User. Both responses are defined below along with an example JSON response.

Table 6. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

404

The object you requested doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

503

The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Table 7. Response Body for a single User Action Log

action.actioneeUserId [UUID]

The Id of the User that was actioned.

action.actionerUserId [UUID]

The Id of the User that took the action on the User. If the action was initiated by FusionAuth this value will not be provided.

action.applicationIds [Array<UUID>]

This parameter if provided specifies the scope of the User Action. When an Action is scoped to one or more Applications the Application Ids will be provided in this parameter.

action.comment [String]

An optional comment provided when the Action was created, updated or canceled. This value will always be the last comment set on the action, see history for previous values.

action.createInstant [Long]

The instant that the User Action was taken.

action.emailUserOnEnd [Boolean]

Whether FusionAuth will email the User when a time-based User Actions expires.

action.endEventSent [Boolean]

Whether FusionAuth will send events when a time-based User Actions expires.

action.expiry [Long]

The expiration instant of the User Action.

action.history.historyItems [Array]

The historical data for the User Action Log. Each time the User Action is modified or when the User Action is canceled a new historyItem is recorded.

action.history.historyItems[x].actionerUserId [UUID]

The Id of the User that took the modified (or created) the User Action.

action.history.historyItems[x].comment [String]

An optional comment provided when the Action was created, updated or canceled.

action.history.historyItems[x].createInstant [Long]

The instant that this historical modification or creation was performed.

action.history.historyItems[x].expiry [Long]

The instant that the User Action expired at previously.

action.id [UUID]

The Id of the User Action record.

action.localizedOption [String]

The localized version of the User Action Option that was selected by the actioner.

action.localizedReason [String]

The localized version of the User Action Reason that was selected by the actioner.

action.notifyUserOnEnd [String]

Whether or not FusionAuth will send events to registered Webhooks when a time-based User Action expires.

action.option [String]

The non-localized version of the User Action Option that was selected by the actioner.

action.reason [String]

The non-localized version of the User Action Reason that was selected by the actioner.

action.reasonCode [String]

The User Action Reason code that was selected by the actioner.

action.userActionId [UUID]

The unique Id of the User Action. This Id can be used to retrieve the User Action using the Retrieve a User Action API.

Example Response JSON for a Single User Action
{
  "action": {
    "actioneeUserId": "00000000-0000-0000-0000-000000000001",
    "actionerUserId": "00000000-0000-0000-0000-000000000002",
    "applicationIds": [
      "00000000-0000-0000-0000-000000000042",
      "00000000-0000-0000-0000-000000000043"
    ],
    "comment": "This user is still being a jerk",
    "createInstant": 1471786483322,
    "emailUserOnEnd": false,
    "endEventSent": false,
    "expiry": 1471586483322,
    "historyItems": [
      {
        "actionerUserId": "00000000-0000-0000-0000-000000000002",
        "comment": "This user is still being a jerk",
        "createInstant": 1471786433322,
        "expiry": 1471496483322
      }
    ],
    "id": "00000000-0000-0000-0000-013500000002",
    "localizedOption": "Lock account full",
    "localizedReason": "Community rules infraction",
    "notifyUserOnEnd": true,
    "option": "Lock account full",
    "reason": "Community rules infraction",
    "reasonCode": "FRAC",
    "userActionId": "00000000-0000-0000-0000-000000000010"
  }
}
Table 8. Response Body for all User Actions

actions [Array]

The list of User Actions.

actions[x].actioneeUserId [UUID]

The Id of the User that was actioned.

actions[x].actionerUserId [UUID]

The Id of the User that was took the action on the User.

actions[x].applicationIds [Array<UUID>]

The list of Application ids that the action was performed in.

actions[x].comment [String]

The comment left by the actioner. This is the last User to touch the User Action (i.e. if the User Action was updated, this will be the comment left by the User that updated it).

actions[x].createInstant [Long]

The instant that the User Action was created.

actions[x].emailUserOnEnd [Boolean]

Whether FusionAuth will email the User when a time-based User Actions expires.

actions[x].endEventSent [Boolean]

Whether FusionAuth will send events when a time-based User Actions expires.

actions[x].expiry [Long]

The expiration instant of the User Action.

actions[x].history.historyItems [Array]

The historical data for the User Action. Each time the User Action is modified a new historyItem is added to the list.

actions[x].history.historyItems[x].actionerUserId [UUID]

The Id of the User that took the modified (or created) the User Action.

actions[x].history.historyItems[x].comment [String]

The message that the actioner added when they modified (or created) this User Action.

actions[x].history.historyItems[x].createInstant [Long]

The instant that this historical modification or creation was performed.

actions[x].history.historyItems[x].expiry [Long]

The instant that the User Action expired at previously.

actions[x].id [UUID]

The Id of the User Action.

actions[x].localizedOption [String]

The localized version of the User Action Option that was selected by the actioner.

actions[x].localizedReason [String]

The localized version of the User Action Reason that was selected by the actioner.

actions[x].notifyUserOnEnd [String]

Whether or not FusionAuth will send events to registered Webhooks when a time-based User Action expires.

actions[x].option [String]

The non-localized version of the User Action Option that was selected by the actioner.

actions[x].reason [String]

The non-localized version of the User Action Reason that was selected by the actioner.

actions[x].reasonCode [String]

The User Action Reason code that was selected by the actioner.

Example Response JSON for all the User Actions
{
  "actions": [
    {
      "actioneeUserId": "00000000-0000-0000-0000-000000000001",
      "actionerUserId": "00000000-0000-0000-0000-000000000002",
      "applicationIds": [
        "00000000-0000-0000-0000-000000000042",
        "00000000-0000-0000-0000-000000000043"
      ],
      "comment": "This user is still being a jerk",
      "createInstant": 1471786483322,
      "emailUserOnEnd": false,
      "endEventSent": false,
      "expiry": 1471586483322,
      "historyItems": [
        {
          "actionerUserId": "00000000-0000-0000-0000-000000000002",
          "comment": "This user is still being a jerk",
          "createInstant": 1471786433322,
          "expiry": 1471496483322
        }
      ],
      "id": "00000000-0000-0000-0000-013500000002",
      "localizedOption": "Lock account full",
      "localizedReason": "Community rules infraction",
      "notifyUserOnEnd": true,
      "option": "Lock account full",
      "reason": "Community rules infraction",
      "reasonCode": "FRAC",
      "userActionId": "00000000-0000-0000-0000-000000000010"
    }
  ]
}

4. Update a Previously Taken Action

This API is used to update a User Action that was previously taken on a User. User Actions are the method that FusionAuth uses to discipline, reward and interact with Users.

4.1. Request

Update an in progress Action by Id

URI

PUT /api/user/action/{actionId}

Table 9. Request Parameters

actionId [UUID] Required

The Id of the User Action being updated.

Table 10. Request Body

action.actionerUserId [UUID] Required

The Id of the User that is taking the action on the User.

action.comment [String] Optional

The comment left by the actioner.

action.emailUser [Boolean] Optional defaults to false

Whether FusionAuth should send an email to the User.

action.expiry [Long] Optional

The expiration instant of this User Action. This is required for time-based User Actions.

action.notifyUser [Boolean] Optional defaults to false

The notifyUser flag that is passed along in any events FusionAuth sends to registered Webhooks.

broadcast [Boolean] Optional defaults to false

Whether or not FusionAuth will broadcast the User Action to any registered Webhooks.

Example Request JSON
{
  "broadcast": true,
  "action": {
    "actionerUserId": "00000000-0000-0000-0000-000000000002",
    "comment": "This user is still being a jerk",
    "emailUser": true,
    "expiry": 1471586483322,
    "notifyUser": true
  }
}

4.2. Response

The response for this API contains the User Action along with any event and email information that was generated by FusionAuth.

Table 11. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

404

The object you are trying to updated doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

503

The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

504

One or more Webhook endpoints returned an invalid response or were unreachable. Based on the transaction configuration for this event your action cannot be completed. A stack trace is provided and logged in the FusionAuth log files.

Table 12. Response Body for a single User Action Log

action.actioneeUserId [UUID]

The Id of the User that was actioned.

action.actionerUserId [UUID]

The Id of the User that took the action on the User. If the action was initiated by FusionAuth this value will not be provided.

action.applicationIds [Array<UUID>]

This parameter if provided specifies the scope of the User Action. When an Action is scoped to one or more Applications the Application Ids will be provided in this parameter.

action.comment [String]

An optional comment provided when the Action was created, updated or canceled. This value will always be the last comment set on the action, see history for previous values.

action.createInstant [Long]

The instant that the User Action was taken.

action.emailUserOnEnd [Boolean]

Whether FusionAuth will email the User when a time-based User Actions expires.

action.endEventSent [Boolean]

Whether FusionAuth will send events when a time-based User Actions expires.

action.expiry [Long]

The expiration instant of the User Action.

action.history.historyItems [Array]

The historical data for the User Action Log. Each time the User Action is modified or when the User Action is canceled a new historyItem is recorded.

action.history.historyItems[x].actionerUserId [UUID]

The Id of the User that took the modified (or created) the User Action.

action.history.historyItems[x].comment [String]

An optional comment provided when the Action was created, updated or canceled.

action.history.historyItems[x].createInstant [Long]

The instant that this historical modification or creation was performed.

action.history.historyItems[x].expiry [Long]

The instant that the User Action expired at previously.

action.id [UUID]

The Id of the User Action record.

action.localizedOption [String]

The localized version of the User Action Option that was selected by the actioner.

action.localizedReason [String]

The localized version of the User Action Reason that was selected by the actioner.

action.notifyUserOnEnd [String]

Whether or not FusionAuth will send events to registered Webhooks when a time-based User Action expires.

action.option [String]

The non-localized version of the User Action Option that was selected by the actioner.

action.reason [String]

The non-localized version of the User Action Reason that was selected by the actioner.

action.reasonCode [String]

The User Action Reason code that was selected by the actioner.

action.userActionId [UUID]

The unique Id of the User Action. This Id can be used to retrieve the User Action using the Retrieve a User Action API.

Example Response JSON for a Single User Action
{
  "action": {
    "actioneeUserId": "00000000-0000-0000-0000-000000000001",
    "actionerUserId": "00000000-0000-0000-0000-000000000002",
    "applicationIds": [
      "00000000-0000-0000-0000-000000000042",
      "00000000-0000-0000-0000-000000000043"
    ],
    "comment": "This user is still being a jerk",
    "createInstant": 1471786483322,
    "emailUserOnEnd": false,
    "endEventSent": false,
    "expiry": 1471586483322,
    "historyItems": [
      {
        "actionerUserId": "00000000-0000-0000-0000-000000000002",
        "comment": "This user is still being a jerk",
        "createInstant": 1471786433322,
        "expiry": 1471496483322
      }
    ],
    "id": "00000000-0000-0000-0000-013500000002",
    "localizedOption": "Lock account full",
    "localizedReason": "Community rules infraction",
    "notifyUserOnEnd": true,
    "option": "Lock account full",
    "reason": "Community rules infraction",
    "reasonCode": "FRAC",
    "userActionId": "00000000-0000-0000-0000-000000000010"
  }
}

5. Cancel a Previously Taken Action

This API is used to cancel a User Action that was previously taken on a User. User Actions are the method that FusionAuth uses to discipline, reward and interact with Users.

5.1. Request

Cancel in progress Action by Id

URI

DELETE /api/user/action/{actionId}

Table 13. Request Parameters

actionId [UUID] Required

The Id of the User Action being canceled.

Table 14. Request Body

action.actionerUserId [UUID] Required

The Id of the User that is taking the action on the User.

action.comment [String] Optional

The comment left by the actioner.

action.emailUser [Boolean] Optional defaults to false

Whether FusionAuth should send an email to the User.

action.expiry [Long] Optional

The expiration instant of this User Action. This is required for time-based User Actions.

action.notifyUser [Boolean] Optional defaults to false

The notifyUser flag that is passed along in any events FusionAuth sends to registered Webhooks.

broadcast [Boolean] Optional defaults to false

Whether or not FusionAuth will broadcast the User Action to any registered Webhooks.

Example Request JSON
{
  "broadcast": true,
  "action": {
    "actionerUserId": "00000000-0000-0000-0000-000000000002",
    "comment": "This user is behaving now",
    "emailUser": true,
    "notifyUser": true
  }
}

5.2. Response

The response for this API contains the User Action along with any event and email information that was generated by FusionAuth.

Table 15. Response Codes
Code Description

200

The request was successful. The response will be empty.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

404

The object you are trying to delete doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

503

The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

504

One or more Webhook endpoints returned an invalid response or were unreachable. Based on the transaction configuration for this event your action cannot be completed. A stack trace is provided and logged in the FusionAuth log files.

Table 16. Response Body for a single User Action Log

action.actioneeUserId [UUID]

The Id of the User that was actioned.

action.actionerUserId [UUID]

The Id of the User that took the action on the User. If the action was initiated by FusionAuth this value will not be provided.

action.applicationIds [Array<UUID>]

This parameter if provided specifies the scope of the User Action. When an Action is scoped to one or more Applications the Application Ids will be provided in this parameter.

action.comment [String]

An optional comment provided when the Action was created, updated or canceled. This value will always be the last comment set on the action, see history for previous values.

action.createInstant [Long]

The instant that the User Action was taken.

action.emailUserOnEnd [Boolean]

Whether FusionAuth will email the User when a time-based User Actions expires.

action.endEventSent [Boolean]

Whether FusionAuth will send events when a time-based User Actions expires.

action.expiry [Long]

The expiration instant of the User Action.

action.history.historyItems [Array]

The historical data for the User Action Log. Each time the User Action is modified or when the User Action is canceled a new historyItem is recorded.

action.history.historyItems[x].actionerUserId [UUID]

The Id of the User that took the modified (or created) the User Action.

action.history.historyItems[x].comment [String]

An optional comment provided when the Action was created, updated or canceled.

action.history.historyItems[x].createInstant [Long]

The instant that this historical modification or creation was performed.

action.history.historyItems[x].expiry [Long]

The instant that the User Action expired at previously.

action.id [UUID]

The Id of the User Action record.

action.localizedOption [String]

The localized version of the User Action Option that was selected by the actioner.

action.localizedReason [String]

The localized version of the User Action Reason that was selected by the actioner.

action.notifyUserOnEnd [String]

Whether or not FusionAuth will send events to registered Webhooks when a time-based User Action expires.

action.option [String]

The non-localized version of the User Action Option that was selected by the actioner.

action.reason [String]

The non-localized version of the User Action Reason that was selected by the actioner.

action.reasonCode [String]

The User Action Reason code that was selected by the actioner.

action.userActionId [UUID]

The unique Id of the User Action. This Id can be used to retrieve the User Action using the Retrieve a User Action API.

Example Response JSON for a Single User Action
{
  "action": {
    "actioneeUserId": "00000000-0000-0000-0000-000000000001",
    "actionerUserId": "00000000-0000-0000-0000-000000000002",
    "applicationIds": [
      "00000000-0000-0000-0000-000000000042",
      "00000000-0000-0000-0000-000000000043"
    ],
    "comment": "This user is behaving now",
    "createInstant": 1471786483322,
    "emailUserOnEnd": false,
    "endEventSent": false,
    "expiry": 1471586483322,
    "historyItems": [
      {
        "actionerUserId": "00000000-0000-0000-0000-000000000002",
        "comment": "This user is being a jerk",
        "createInstant": 1471786433322,
        "expiry": 1471496483322
      },
      {
        "actionerUserId": "00000000-0000-0000-0000-000000000002",
        "comment": "This user is still being a jerk",
        "createInstant": 1471786433322,
        "expiry": 1471496483322
      }
    ],
    "id": "00000000-0000-0000-0000-013500000003",
    "event": {
      "action": "Lock account full",
      "actionId": "00000000-0000-0000-0000-000000000010",
      "actioneeUserId": "00000000-0000-0000-0000-000000000001",
      "actionerUserId": "00000000-0000-0000-0000-000000000002",
      "comment": "This user is behaving now",
      "createInstant": 1471786483322,
      "email": {
        "from": {
          "address": "support@fusionauth.io",
          "display": "FusionAuth Support"
        },
        "html": "...",
        "subject": "You account has been unlocked",
        "text": "...",
        "to": {
          "address": "foo@bar.com",
          "display": "Foo Jones"
        }
      },
      "expiry": 1471586483322,
      "localizedAction": "Lock account",
      "localizedOption": "Lock account full",
      "localizedReason": "Community rules infraction",
      "notifyUser": false,
      "option": "Lock account full",
      "emailedUser": false,
      "phase": "cancel",
      "reason": "Community rules infraction",
      "reasonCode": "FRAC"
    },
    "notifyUserOnEnd": true,
    "option": "Lock account full",
    "reason": "Community rules infraction",
    "reasonCode": "FRAC",
    "userActionId": "00000000-0000-0000-0000-000000000010"
  }
}