Entity APIs

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

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.

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

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

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

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

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.

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

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.

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

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.

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.

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

{
  "search": {
    "ids": [
      "a6e3ed2d-582b-4ec3-aa3f-4323c8f39fe9",
      "00000000-0000-0001-0000-000000000000"
    ]
  }
}

{
  "search": {
    "numberOfResults": 25,
    "queryString": "api",
    "sortFields": [
      {
        "name": "name",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

{
  "search": {
    "numberOfResults": 25,
    "queryString": "piper",
    "sortFields": [
      {
        "name": "name",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

{
  "search": {
    "numberOfResults": 25,
    "queryString": "*",
    "sortFields": [
      {
        "name": "name",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

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.

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

{
  "search": {
    "ids": [
      "a6e3ed2d-582b-4ec3-aa3f-4323c8f39fe9",
      "00000000-0000-0001-0000-000000000000"
    ]
  }
}

{
  "search": {
    "numberOfResults": 25,
    "query": "{\"match\":{\"name\":{\"query\":\"email_api\"}}}",
    "sortFields": [
      {
        "missing": "_first",
        "name": "name",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

{
  "search": {
    "numberOfResults": 25,
    "query": "{\"match\":{\"data.audited\":{\"query\":\"true\"}}}",
    "sortFields": [
      {
        "missing": "_first",
        "name": "name",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

{
  "search": {
    "numberOfResults": 25,
    "queryString": "name:*api*",
    "sortFields": [
      {
        "missing": "_first",
        "name": "name",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

{
  "search": {
    "numberOfResults": 25,
    "queryString": "tenantId:39666465-6535-3731-3139-666363356438",
    "sortFields": [
      {
        "missing": "_first",
        "name": "name",
        "order": "asc"
      }
    ],
    "startRow": 0
  }
}

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.

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