FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
      • Overview
      • Java Spring
      • Python Django
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Microsoft Azure AD B2C
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
        • Okta
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
        • Okta
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
      • URL Validation
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • PagerDuty
      • Tableau Cloud
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • Amazon API Gateway
      • Kong Gateway
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
    • Events & Webhooks
      • Overview
      • Writing a Webhook
      • Securing Webhooks
      • Events
        • Overview
        • Audit Log Create
        • Event Log Create
        • JWT Public Key Update
        • JWT Refresh
        • JWT Refresh Token Revoke
        • Kickstart Success
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • User Action
        • User Bulk Create
        • User Create
        • User Create Complete
        • User Deactivate
        • User Delete
        • User Delete Complete
        • User Email Update
        • User Email Verified
        • User IdP Link
        • User IdP Unlink
        • User Login Failed
        • User Login Id Dup. Create
        • User Login Id Dup. Update
        • User Login New Device
        • User Login Success
        • User Login Suspicious
        • User Password Breach
        • User Password Reset Send
        • User Password Reset Start
        • User Password Reset Success
        • User Password Update
        • User Reactivate
        • User Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Registration Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Application Specific Email Templates
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • Lambdas
      • Overview
      • Apple Reconcile
      • Client Cred. JWT Populate
      • Epic Games Reconcile
      • External JWT Reconcile
      • Facebook Reconcile
      • Google Reconcile
      • HYPR Reconcile
      • JWT Populate
      • LDAP Connector Reconcile
      • LinkedIn Reconcile
      • Nintendo Reconcile
      • OpenID Connect Reconcile
      • SAML v2 Populate
      • SAML v2 Reconcile
      • SCIM Group Req. Converter
      • SCIM Group Resp. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Self-Service Registration
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
      • Kickstart Custom Theme
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

    Actioning Users

    Overview

    This page contains the APIs that are used for actioning users.

    Once you have created the User Actions, either via the administrative user interface or the User Actions API, you use this API to invoke a User Action on a User.

    • Take an Action on a User

    • Retrieve a Previously Taken Action

    • Update a Previously Taken Action

    • Cancel a Previously Taken Action

    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.

    Request

    Take an action on a User

    URI

    POST /api/user/action

    Request Headers

    X-FusionAuth-TenantId [String] Optional

    The unique Id of the tenant used to scope this API request.

    The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

    Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

    See Making an API request using a Tenant Id for additional information.

    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"
      }
    }

    Response

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

    Table 1. 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. This status will also be returned if a paid FusionAuth license is required and is not present.

    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.

    Response Body

    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.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.insertInstant [Long]

    The instant that the User Action was taken.

    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",
        "insertInstant": 1595361142909,
        "lastUpdateInstant": 1595361143101,
        "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"
      }
    }

    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.

    Request

    Retrieve a specific User Action Log by Id.

    URI

    GET /api/user/action/{actionId}

    Request Parameters

    actionId [UUID] Required

    The unique Id of the Action to retrieve.

    Request Headers

    X-FusionAuth-TenantId [String] Optional

    The unique Id of the tenant used to scope this API request.

    The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

    Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

    See Making an API request using a Tenant Id for additional information.

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

    URI

    GET /api/user/action?userId={userId}&active={active}&preventingLogin={preventingLogin}

    Request Parameters

    userId [UUID] Required

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

    active [Boolean] Optional

    When this parameter is provided and set to true, only active actions will be returned. When this parameter is provided and set to false, only the inactive actions will be returned. When this parameter is omitted, all actions will be returned.

    An active action is a time based action that has not yet expired or been canceled. An inactive action is either a time based action that has expired, canceled or an action that is not time based.

    This parameter and preventingLogin are mutually exclusive.

    preventingLogin [Boolean] Optional Available since 1.4.0

    When this value is provided and set to true, only active actions that are preventing the user from login will be returned. Omitting this parameter, or setting this parameter to false does not affect the API behavior.

    This parameter and active are mutually exclusive because an action that is preventing login is always active.

    Request Headers

    X-FusionAuth-TenantId [String] Optional

    The unique Id of the tenant used to scope this API request.

    The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

    Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

    See Making an API request using a Tenant Id for additional information.

    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 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. This status will also be returned if a paid FusionAuth license is required and is not present.

    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.

    Response Body

    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.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.insertInstant [Long]

    The instant that the User Action was taken.

    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",
        "insertInstant": 1595361142909,
        "lastUpdateInstant": 1595361143101,
        "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"
      }
    }

    Response Body

    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].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.

    action[x].insertInstant [Long]

    The instant that the User Action was taken.

    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",
          "insertInstant": 1595361142909,
          "lastUpdateInstant": 1595361143101,
          "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"
        }
      ]
    }

    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.

    Request

    Update an in progress Action by Id

    URI

    PUT /api/user/action/{actionId}

    Request Parameters

    actionId [UUID] Required

    The Id of the User Action being updated.

    Request Headers

    X-FusionAuth-TenantId [String] Optional

    The unique Id of the tenant used to scope this API request.

    The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

    Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

    See Making an API request using a Tenant Id for additional information.

    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
      }
    }

    Response

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

    Table 3. 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. This status will also be returned if a paid FusionAuth license is required and is not present.

    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 update 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.

    Response Body

    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.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.insertInstant [Long]

    The instant that the User Action was taken.

    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",
        "insertInstant": 1595361142909,
        "lastUpdateInstant": 1595361143101,
        "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"
      }
    }

    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.

    Request

    Cancel in progress Action by Id

    URI

    DELETE /api/user/action/{actionId}

    Request Parameters

    actionId [UUID] Required

    The Id of the User Action being canceled.

    Request Headers

    X-FusionAuth-TenantId [String] Optional

    The unique Id of the tenant used to scope this API request.

    The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

    Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

    See Making an API request using a Tenant Id for additional information.

    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
      }
    }

    Response

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

    Table 4. 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. This status will also be returned if a paid FusionAuth license is required and is not present.

    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.

    Response Body

    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.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.insertInstant [Long]

    The instant that the User Action was taken.

    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",
        "insertInstant": 1595361142909,
        "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,
          "lastUpdateInstant": 1595361143101,
          "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"
      }
    }

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.

    © 2023 FusionAuth
    How-to
    Subscribe for developer updates