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

    Entity APIs

    FusionAuth Reactor logo

    This feature is only available in paid plans. Please visit our pricing page to learn more.

    Overview

    This page contains the APIs for managing Entities as well as searching them. Entity core concepts may also be helpful.

    This API has been available since 1.26.0

    • Create an Entity

    • Retrieve an Entity

    • Update an Entity

    • Delete an Entity

    • Search for Entities

    Create an Entity

    This API is used to create an Entity. Specifying an Id on the URI will instruct FusionAuth to use that Id when creating the Entity. Otherwise, FusionAuth will generate an Id for the Entity.

    Request

    Create an Entity without providing an Id. An Id will be automatically generated.

    URI

    POST /api/entity

    Request Headers

    X-FusionAuth-TenantId [String] Optional

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

    When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request. 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.

    Create an Entity with the provided Id

    URI

    POST /api/entity/{entityId}

    Request Parameters

    entityId [UUID] Optional defaults to secure random UUID

    The Id to use for the new Entity. If not specified a secure random UUID will be generated.

    Request Body

    entity.data [Object] Optional

    An object that can hold any information about the Entity that should be persisted. Please review the limits on data field types as you plan for and build your custom data schema.

    entity.clientId [String] Optional

    The OAuth 2.0 client Id. If you leave this blank during a POST, the value of the Entity Id will be used.

    entity.clientSecret [String] Optional

    The OAuth 2.0 client secret. If you leave this blank during a POST, a secure secret will be generated for you. If you leave this blank during PUT, the previous value will be maintained. For both POST and PUT you can provide a value and it will be stored.

    entity.name [String] Required

    A descriptive name for the Entity (i.e. "Raviga" or "Email Service").

    entity.type.id [UUID] Required

    The Id of the Entity Type. Types are consulted for permission checks.

    Example Request JSON
    
    {
      "entity": {
        "clientId": "092dbded-30af-4149-9c61-b578f2c72f59",
        "clientSecret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
        "data": {
          "companyType": "Legal"
        },
        "type": {
          "id": "092dbded-30af-4149-9c61-b578f2c72f57"
        },
        "name": "Raviga"
      }
    }

    Request Headers

    X-FusionAuth-TenantId [String] Optional

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

    When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request. 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 the information for the Entity that was created.

    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.

    Response Body

    entity.data [Object]

    An object that can hold any information about the Entity that should be persisted. Please review the limits on data field types as you plan for and build your custom data schema.

    entity.clientId [String]

    The OAuth 2.0 client Id.

    entity.clientSecret [String]

    The OAuth 2.0 client secret.

    entity.id [UUID]

    The unique Id of the Entity.

    entity.insertInstant [Long]

    The instant that the Entity was added to the FusionAuth database.

    entity.lastUpdateInstant [Long]

    The instant that the Entity was last updated in the FusionAuth database.

    entity.name [String]

    A descriptive name for the Entity (i.e. "Raviga" or "Email Service").

    entity.tenantId [UUID]

    The Id of the Tenant to which this Entity belongs.

    entity.type [Object]

    The Entity Type of this Entity. Consult the Entity Type documentation for more details about the fields of this object.

    Example Response JSON for an Entity
    
    {
      "entity": {
        "clientId": "092dbded-30af-4149-9c61-b578f2c72f59",
        "clientSecret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
        "data": {
          "companyType": "Legal"
        },
        "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
        "insertInstant": 1595361142909,
        "lastUpdateInstant": 1595361143101,
        "name": "Raviga",
        "tenantId": "30663132-6464-6665-3032-326466613934",
        "type": {
          "id": "4838d96a-4e7b-42c6-a4a1-ebc64952e1c8",
          "insertInstant": 1518962408732,
          "jwtConfiguration": {
            "enabled": false,
            "timeToLiveInSeconds": 60
          },
          "lastUpdateInstant": 1518962408732,
          "name": "Customers"
        }
      }
    }

    Retrieve an Entity

    This API is used to retrieve one Entity.

    Request

    Retrieve a single Entity by Id

    URI

    GET /api/entity/{entityId}

    Request Parameters

    entityId [UUID] Required

    The Id of the Entity 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.

    Response

    The response for this API contains a single Entity.

    Table 2. Response Codes
    Code Description

    200

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

    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

    entity.data [Object]

    An object that can hold any information about the Entity that should be persisted. Please review the limits on data field types as you plan for and build your custom data schema.

    entity.clientId [String]

    The OAuth 2.0 client Id.

    entity.clientSecret [String]

    The OAuth 2.0 client secret.

    entity.id [UUID]

    The unique Id of the Entity.

    entity.insertInstant [Long]

    The instant that the Entity was added to the FusionAuth database.

    entity.lastUpdateInstant [Long]

    The instant that the Entity was last updated in the FusionAuth database.

    entity.name [String]

    A descriptive name for the Entity (i.e. "Raviga" or "Email Service").

    entity.tenantId [UUID]

    The Id of the Tenant to which this Entity belongs.

    entity.type [Object]

    The Entity Type of this Entity. Consult the Entity Type documentation for more details about the fields of this object.

    Example Response JSON for an Entity
    
    {
      "entity": {
        "clientId": "092dbded-30af-4149-9c61-b578f2c72f59",
        "clientSecret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
        "data": {
          "companyType": "Legal"
        },
        "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
        "insertInstant": 1595361142909,
        "lastUpdateInstant": 1595361143101,
        "name": "Raviga",
        "tenantId": "30663132-6464-6665-3032-326466613934",
        "type": {
          "id": "4838d96a-4e7b-42c6-a4a1-ebc64952e1c8",
          "insertInstant": 1518962408732,
          "jwtConfiguration": {
            "enabled": false,
            "timeToLiveInSeconds": 60
          },
          "lastUpdateInstant": 1518962408732,
          "name": "Customers"
        }
      }
    }

    Update an Entity

    This API is used to update an existing Entity.

    You must specify the Id of the Entity you are updating on the URI.

    You must specify all of the properties of the Entity when calling this API with the PUT HTTP method. When used with PUT, this API doesn’t merge the existing Entity and your new data. It replaces the existing Entity with your new data.

    Utilize the PATCH HTTP method to send specific changes to merge into an existing Entity.

    Request

    Update an Entity by Id

    URI

    PUT /api/entity/{entityId}

    PATCH /api/entity/{entityId}

    Available since 1.39.0

    When using the PATCH method, you can either use the same request body documentation that is provided for the PUT request for backward compatibility. Or you may use either JSON Patch/RFC 6902 or JSON Merge Patch/RFC 7396. See the PATCH documentation for more information.

    Available since 1.12.0

    When using the PATCH method, use the same request body documentation that is provided for the PUT request. The PATCH method will merge the provided request parameters into the existing object, this means all parameters are optional when using the PATCH method and you only provide the values you want changed. A null value can be used to remove a value. Patching an Array will result in all values from the new list being appended to the existing list, this is a known limitation to the current implementation of PATCH.

     

    Request Parameters

    entityId [UUID] Required

    The Id of the Entity to update.

    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

    entity.data [Object] Optional

    An object that can hold any information about the Entity that should be persisted. Please review the limits on data field types as you plan for and build your custom data schema.

    entity.clientId [String] Optional

    The OAuth 2.0 client Id. If you leave this blank during a POST, the value of the Entity Id will be used.

    entity.clientSecret [String] Optional

    The OAuth 2.0 client secret. If you leave this blank during a POST, a secure secret will be generated for you. If you leave this blank during PUT, the previous value will be maintained. For both POST and PUT you can provide a value and it will be stored.

    entity.name [String] Required

    A descriptive name for the Entity (i.e. "Raviga" or "Email Service").

    entity.type.id [UUID] Required

    The Id of the Entity Type. Types are consulted for permission checks.

    Example Request JSON
    
    {
      "entity": {
        "clientId": "092dbded-30af-4149-9c61-b578f2c72f59",
        "clientSecret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
        "data": {
          "companyType": "Legal"
        },
        "type": {
          "id": "092dbded-30af-4149-9c61-b578f2c72f57"
        },
        "name": "Raviga"
      }
    }

    Response

    The response for this API contains the new information for the Entity that was updated.

    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.

    Response Body

    entity.data [Object]

    An object that can hold any information about the Entity that should be persisted. Please review the limits on data field types as you plan for and build your custom data schema.

    entity.clientId [String]

    The OAuth 2.0 client Id.

    entity.clientSecret [String]

    The OAuth 2.0 client secret.

    entity.id [UUID]

    The unique Id of the Entity.

    entity.insertInstant [Long]

    The instant that the Entity was added to the FusionAuth database.

    entity.lastUpdateInstant [Long]

    The instant that the Entity was last updated in the FusionAuth database.

    entity.name [String]

    A descriptive name for the Entity (i.e. "Raviga" or "Email Service").

    entity.tenantId [UUID]

    The Id of the Tenant to which this Entity belongs.

    entity.type [Object]

    The Entity Type of this Entity. Consult the Entity Type documentation for more details about the fields of this object.

    Example Response JSON for an Entity
    
    {
      "entity": {
        "clientId": "092dbded-30af-4149-9c61-b578f2c72f59",
        "clientSecret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
        "data": {
          "companyType": "Legal"
        },
        "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
        "insertInstant": 1595361142909,
        "lastUpdateInstant": 1595361143101,
        "name": "Raviga",
        "tenantId": "30663132-6464-6665-3032-326466613934",
        "type": {
          "id": "4838d96a-4e7b-42c6-a4a1-ebc64952e1c8",
          "insertInstant": 1518962408732,
          "jwtConfiguration": {
            "enabled": false,
            "timeToLiveInSeconds": 60
          },
          "lastUpdateInstant": 1518962408732,
          "name": "Customers"
        }
      }
    }

    Delete an Entity

    This API is used to delete an Entity. You must specify the Id of the Entity on the URI.

    Request

    Delete an Entity By Id

    URI

    DELETE /api/entity/{entityId}

    Request Parameters

    entityId [UUID] Required

    The Id of the Entity to delete.

    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 when only one tenant has been configured. If there is more than one tenant, the tenant Id is required.

    Supply the tenant Id via this header or by using an API Key scoped to a tenant, which implicitly supplies the tenant Id.

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

    Response

    This API does not return a JSON response body.

    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.

    Search for Entities

    This API is used to search for Entities. This API may be called using the GET or POST HTTP methods. Examples of each are provided below. The POST method is provided to allow for a richer request object without worrying about exceeding the maximum length of a URL. Calling this API with either the GET or POST HTTP method will provide the same search results given the same query parameters.

    Request

    Which search query parameters are available and how they behave depends on the search engine type. Read more about the different types of search engines.

    Database Search Engine

    This is a good choice for smaller installs, embedded scenarios, or other places where the additional capability of Elasticsearch is not required.

    Search for Entities by Id

    URI

    GET /api/entity/search?ids={uuid}&ids={uuid}

    Search for Entities by a query string

    URI

    GET /api/entity/search?queryString={queryString}

    Search for Entities by a query string and sort the response

    URI

    GET /api/entity/search?queryString={queryString}&sortFields[0].name={name}&sortFields[0].order={order}

    Request Parameters

    accurateTotal [Boolean] Optional Defaults to false

    Set this value equal to true to receive an accurate hit count on the API response.

    By default the search engine will limit the hit count to 10,000 entities. This means that even if your query may match more than 10,000 entities, the returned total count will be 10,000. This is adequate for many use cases such as pagination and general purpose queries. If you are looking for an accurate entity count that can exceed 10,000 matches, you will want to set this value equal to true.

    ids [UUID] Optional

    An Entity Id to retrieve. By specifying this URL parameter multiple times you can lookup multiple Entities. Using this parameter is mutually exclusive with the queryString field and is not paginated or sorted using the sortFields field.

    numberOfResults [Integer] Optional defaults to 25

    The number of search results to return. Used for pagination.

    queryString [String] Optional

    A query string that is used to search for Entities. Using this parameter is mutually exclusive with the ids field.

    Database search limits effective queries to single search terms that may match the following fields on the Entities or their Entity Type:

    • clientId

    • name

    • entityType.name

      The search matches against all of these fields and any entity with a matching field will be returned. The match is case-insensitive, and you may not search by prefix or suffix. Whitespace is not allowed in the search. Regular expressions may not be used. A value of * will match all records.

    startRow [Integer] Optional defaults to 0

    The start row within the search results to return. Used for pagination.

    sortFields [Array] Optional

    An array of sort fields used to sort the result. The order the sort fields are provided will be maintained in the sorted output.

    sortFields[x].name [String] Required

    The name of the field to sort.

    Required if sortFields is provided.

    The following field names are supported for the database search engine:

    • clientId

    • insertInstant

    • lastUpdateInstant

    • name

    • tenantId

    • typeId

    sortFields[x].order [String] Optional defaults to asc

    The order to sort the specified field. Possible values are:

    • asc

    • desc

    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.

    Search for Entities using a JSON request body. This allows for larger requests than are possible using request parameters.

    URI

    POST /api/entity/search

    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

    search.accurateTotal [Boolean] Optional Defaults to false

    Set this value equal to true to receive an accurate hit count on the API response.

    By default the search engine will limit the hit count to 10,000 entities. This means that even if your query may match more than 10,000 entities, the returned total count will be 10,000. This is adequate for many use cases such as pagination and general purpose queries. If you are looking for an accurate entity count that can exceed 10,000 matches, you will want to set this value equal to true.

    search.ids [UUID] Optional

    An Entity Id to retrieve. By specifying this URL parameter multiple times you can lookup multiple Entities. Using this parameter is mutually exclusive with the queryString field and is not paginated or sorted using the sortFields field.

    search.numberOfResults [Integer] Optional defaults to 25

    The number of search results to return. Used for pagination.

    search.queryString [String] Optional

    A query string that is used to search for Entities. Using this parameter is mutually exclusive with the ids field.

    Database search limits effective queries to single search terms that may match the following fields on the Entities or their Entity Type:

    • clientId

    • name

    • entityType.name

      The search matches against all of these fields and any entity with a matching field will be returned. The match is case-insensitive, and you may not search by prefix or suffix. Whitespace is not allowed in the search. Regular expressions may not be used. A value of * will match all records.

    search.startRow [Integer] Optional defaults to 0

    The start row within the search results to return. Used for pagination.

    search.sortFields [Array] Optional

    An array of sort fields used to sort the result. The order the sort fields are provided will be maintained in the sorted output.

    search.sortFields[x].name [String] Required

    The name of the field to sort.

    Required if sortFields is provided.

    The following field names are supported for the database search engine:

    • clientId

    • insertInstant

    • lastUpdateInstant

    • name

    • tenantId

    • typeId

    search.sortFields[x].order [String] Optional defaults to asc

    The order to sort the specified field. Possible values are:

    • asc

    • desc

    Request Body Examples
    Example Request JSON searching by ids
    
    {
      "search": {
        "ids": [
          "a6e3ed2d-582b-4ec3-aa3f-4323c8f39fe9",
          "00000000-0000-0001-0000-000000000000"
        ]
      }
    }
    Example Request JSON searching by queryString for entities with a matching name
    
    {
      "search": {
        "numberOfResults": 50,
        "queryString": "api",
        "sortFields": [
          {
            "name": "name",
            "order": "asc"
          }
        ],
        "startRow": 0
      }
    }
    Example Request JSON searching by queryString for entities with a clientId, name or type name containing piper.
    
    {
      "search": {
        "numberOfResults": 50,
        "queryString": "piper",
        "sortFields": [
          {
            "name": "name",
            "order": "asc"
          }
        ],
        "startRow": 0
      }
    }
    Example Request JSON to retrieve the first 50 entities, ordered by name, ascending.
    
    {
      "search": {
        "numberOfResults": 50,
        "queryString": "*",
        "sortFields": [
          {
            "name": "name",
            "order": "asc"
          }
        ],
        "startRow": 0
      }
    }

    Elasticsearch Search Engine

    The Elasticsearch engine has advanced querying capabilities and better performance.

    Search for Entities by Id

    URI

    GET /api/entity/search?ids={uuid}&ids={uuid}

    Search for Entities by a query string

    URI

    GET /api/entity/search?queryString={queryString}

    Search for Entities by a query string and sort the response

    URI

    GET /api/entity/search?queryString={queryString}&sortFields[0].name={name}&sortFields[0].order={order}

    Search for Entities by a raw JSON query

    URI

    GET /api/entity/search?query={query}

    Request Parameters

    accurateTotal [Boolean] Optional Defaults to false

    Set this value equal to true to receive an accurate hit count on the API response.

    By default the search engine will limit the hit count to 10,000 entities. This means that even if your query may match more than 10,000 entities, the returned total count will be 10,000. This is adequate for many use cases such as pagination and general purpose queries. If you are looking for an accurate entity count that can exceed 10,000 matches, you will want to set this value equal to true.

    ids [UUID] Optional

    An Entity Id to retrieve. By specifying this URL parameter multiple times you can lookup multiple Entities. Using this parameter is mutually exclusive with the query and queryString fields and is not paginated or sorted using sortFields field.

    Using this parameter will not hit the Elasticsearch index, instead it will cause entities to be retrieved by Id only.

    numberOfResults [Integer] Optional defaults to 25

    The number of search results to return. Used for pagination.

    query [String] Optional

    The raw JSON Elasticsearch query that is used to search for Entities. The ids, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

    It is necessary to use the query parameter when querying against grants in order to achieve expected results, as this field is defined as a nested datatype in the Elasticsearch mapping.

    queryString [String] Optional

    The Elasticsearch query string that is used to search for Entities. The ids, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

    The match is case-insensitive. Whitespace is allowed in the search, but must be URL escaped; for example, using %20 for a space character. Elasticsearch compatible regular expressions may be used, so you may search by prefix or suffix using the * wildcard.

    You may search against specific fields like so: name:*API. This will match only entities with a name ending in a API. You may find the available fields for matching by retrieving the Elasticsearch mapping.

    startRow [Integer] Optional defaults to 0

    The start row within the search results to return. Used for pagination.

    sortFields [Array] Optional

    An array of sort fields used to sort the result. The order the sort fields are provided will be maintained in the sorted output.

    sortFields[x].missing [String] Optional defaults to _last

    The value to substitute if this field is not defined. Two special values may be used:

    • _first When the field is not defined sort this record first.

    • _last When the field is not defined sort this record last.

    sortFields[x].name [String] Optional

    The name of the field to sort.

    Required if sortFields is provided.

    Due to how the search index is structured not all fields on the entity are sortable. The following field names are currently supported.

    • clientId

    • insertInstant

    • lastUpdateInstant

    • name

    • tenantId

    • typeId

    sortFields[x].order [String] Optional defaults to asc

    The order to sort the specified field. Possible values are:

    • asc

    • desc

    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.

    Search for Entities using a JSON request body. This allows for larger requests than are possible using request parameters.

    URI

    POST /api/entity/search

    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

    search.accurateTotal [Boolean] Optional Defaults to false

    Set this value equal to true to receive an accurate hit count on the API response.

    By default the search engine will limit the hit count to 10,000 entities. This means that even if your query may match more than 10,000 entities, the returned total count will be 10,000. This is adequate for many use cases such as pagination and general purpose queries. If you are looking for an accurate entity count that can exceed 10,000 matches, you will want to set this value equal to true.

    search.ids [UUID] Optional

    An Entity Id to retrieve. By specifying this URL parameter multiple times you can lookup multiple Entities. Using this parameter is mutually exclusive with the query and queryString fields and is not paginated or sorted using sortFields field.

    Using this parameter will not hit the Elasticsearch index, instead it will cause entities to be retrieved by Id only.

    search.numberOfResults [Integer] Optional defaults to 25

    The number of search results to return. Used for pagination.

    search.query [String] Optional

    The raw JSON Elasticsearch query that is used to search for Entities. The ids, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

    It is necessary to use the search.query parameter when querying against grants in order to achieve expected results, as this field is defined as a nested datatype in the Elasticsearch mapping.

    search.queryString [String] Optional

    The Elasticsearch query string that is used to search for Entities. The ids, query, and queryString parameters are mutually exclusive, they are listed here in order of precedence.

    The match is case-insensitive. Whitespace is allowed in the search, but must be URL escaped; for example, using %20 for a space character. Elasticsearch compatible regular expressions may be used, so you may search by prefix or suffix using the * wildcard.

    You may search against specific fields like so: name:*API. This will match only entities with a name ending in a API. You may find the available fields for matching by retrieving the Elasticsearch mapping.

    search.startRow [Integer] Optional defaults to 0

    The start row within the search results to return. Used for pagination.

    search.sortFields [Array] Optional

    An array of sort fields used to sort the result. The order the sort fields are provided will be maintained in the sorted output.

    search.sortFields[x].missing [String] Optional defaults to _last

    The value to substitute if this field is not defined. Two special values may be used:

    • _first When the field is not defined sort this record first.

    • _last When the field is not defined sort this record last.

    search.sortFields[x].name [String] Optional

    The name of the field to sort.

    Required if sortFields is provided.

    Due to how the search index is structured not all fields on the entity are sortable. The following field names are currently supported.

    • clientId

    • insertInstant

    • lastUpdateInstant

    • name

    • tenantId

    • typeId

    search.sortFields[x].order [String] Optional defaults to asc

    The order to sort the specified field. Possible values are:

    • asc

    • desc

    Request Body Examples
    Example Request JSON searching by ids
    
    {
      "search": {
        "ids": [
          "a6e3ed2d-582b-4ec3-aa3f-4323c8f39fe9",
          "00000000-0000-0001-0000-000000000000"
        ]
      }
    }
    Example JSON searching by query for entities with a given name
    
    {
      "search": {
        "numberOfResults": 50,
        "query": "{\"match\":{\"name\":{\"query\":\"email_api\"}}}",
        "sortFields": [
          {
            "missing": "_first",
            "name": "name",
            "order": "asc"
          }
        ],
        "startRow": 0
      }
    }
    Example JSON searching by query for entity with custom entity data of audited equal to true
    
    {
      "search": {
        "numberOfResults": 50,
        "query": "{\"match\":{\"data.audited\":{\"query\":\"true\"}}}",
        "sortFields": [
          {
            "missing": "_first",
            "name": "name",
            "order": "asc"
          }
        ],
        "startRow": 0
      }
    }
    Example Request JSON searching by queryString for entities with a name matching a pattern
    
    {
      "search": {
        "numberOfResults": 50,
        "queryString": "name:*api*",
        "sortFields": [
          {
            "missing": "_first",
            "name": "name",
            "order": "asc"
          }
        ],
        "startRow": 0
      }
    }
    Example Request JSON searching by queryString for entities in a specific tenant. A global API key must be used, and you may not use the X-FusionAuth-TenantId header when the search parameters include tenantId
    
    {
      "search": {
        "numberOfResults": 50,
        "queryString": "tenantId:39666465-6535-3731-3139-666363356438",
        "sortFields": [
          {
            "missing": "_first",
            "name": "name",
            "order": "asc"
          }
        ],
        "startRow": 0
      }
    }

    Response

    The response contains the Entity objects that were found as part of the lookup or search. Both the database and Elasticsearch search engines return the response in the same format.

    Table 5. 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

    entities[x] [Array]

    The list of Entity objects.

    entities[x].data [Object]

    An object that can hold any information about the Entity that should be persisted. Please review the limits on data field types as you plan for and build your custom data schema.

    entities[x].clientId [String]

    The OAuth 2.0 client Id.

    entities[x].clientSecret [String]

    The OAuth 2.0 client secret.

    entities[x].id [UUID]

    The unique Id of the Entity.

    entities[x].insertInstant [Long]

    The instant that the Entity was added to the FusionAuth database.

    entities[x].lastUpdateInstant [Long]

    The instant that the Entity was last updated in the FusionAuth database.

    entities[x].name [String]

    A descriptive name for the Entity (i.e. "Raviga" or "Email Service").

    entities[x].tenantId [UUID]

    The Id of the Tenant to which this Entity belongs.

    entities[x].type [Object]

    The Entity Type of this Entity. Consult the Entity Type documentation for more details about the fields of this object.

    Example Response JSON for multiple Entities
    
    {
      "entities": [
        {
          "clientId": "092dbded-30af-4149-9c61-b578f2c72f59",
          "clientSecret": "+fcXet9Iu2kQi61yWD9Tu4ReZ113P6yEAkr32v6WKOQ=",
          "data": {
            "companyType": "Legal"
          },
          "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
          "insertInstant": 1595361142909,
          "lastUpdateInstant": 1595361143101,
          "name": "Raviga",
          "tenantId": "30663132-6464-6665-3032-326466613934",
          "type": {
            "id": "4838d96a-4e7b-42c6-a4a1-ebc64952e1c8",
            "insertInstant": 1518962408732,
            "jwtConfiguration": {
              "enabled": false,
              "timeToLiveInSeconds": 60
            },
            "lastUpdateInstant": 1518962408732,
            "name": "Customers"
          }
        }
      ]
    }

    Flush the Search Engine

    This API is used to issue a flush request to the FusionAuth Search. This will cause any cached data to be written to disk. In practice it is unlikely you’ll find a need for this API in production unless you are performing search requests immediately following an operation that modifies the index and expecting to see the results immediately.

    Request

    Flushes the Search Engine

    URI

    PUT /api/entity/search

    Response

    The response does not contain a body. It only contains one of the status codes below.

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

    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