Resources
🤖 For AI agents: The complete documentation index is available at /docs/llms.txt. A markdown version of this page is available at /docs/apis/entities/entity-types.md.

Entity Type API

Edit on GitHub
View Markdown

This feature is only available in paid plans. To learn more, see our pricing page.

version

Available since version 1.26.0

This page contains the APIs for managing Entity Types. Here are the APIs:

Create an Entity Type#

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

Request#

Global API Key Authentication
Create an Entity Type without providing an Id. An Id will be automatically generated.
POST/api/entity/type
OpenAPI Spec
Global API Key Authentication
Create an Entity Type with the provided Id
POST/api/entity/type/{entityTypeId}
OpenAPI Spec

Request Parameters#

entityTypeId UUID optional Defaults to secure random UUID

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

Request Body#

entityType.data Object optional

An object that can hold any information about the Entity Type that should be persisted.

entityType.jwtConfiguration.accessTokenKeyId UUID optional

The unique id of the signing key used to sign the access token.

Required when enabled is set to true.

entityType.jwtConfiguration.accessTokenVerificationKeyIds Array<UUID> optional Available since 1.69.0

The list of access token verification key Ids that are trusted for this entity type when entity JWTs are presented to /oauth2/introspect or in SCIM use cases. This list always implicitly includes entityType.jwtConfiguration.accessTokenKeyId.

Facilitates key rotation by trusting multiple keys: if you change entityType.jwtConfiguration.accessTokenKeyId to a new key and supply the previous key in this field, FusionAuth will trust JWTs signed by both keys, while only signing JWTs with the new key.

entityType.jwtConfiguration.enabled Boolean optional Defaults to false

Indicates if this application is using the JWT configuration defined here or the global JWT configuration defined by the Tenant. If this is false the signing algorithm configured in the Tenant will be used. If true the signing algorithm defined in this application will be used.

entityType.jwtConfiguration.timeToLiveInSeconds Integer optional

The length of time in seconds the JWT will live before it is expired and no longer valid.

Required when enabled is set to true.

entityType.name String required

A descriptive name for the entity type (i.e. "Customer" or "Email_Service").

Example Request JSON

{
  "entityType": {
    "name": "Customer",
    "data": {
      "createdBy": "jared@fusionauth.io"
    },
    "jwtConfiguration": {
      "accessTokenKeyId": "a7516c7c-6234-4021-b0b4-8870c807aeb2",
      "accessTokenVerificationKeyIds": [
        "f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454"
      ],
      "enabled": true,
      "timeToLiveInSeconds": 3600
    }
  }
}

Response#

The response for this API contains the information for the Entity Type that was created.

Response Codes
CodeDescription
200The request was successful. The response will contain a JSON body.
400The 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.
401You 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.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body#

entityType.data Object

An object that can hold any information about the Entity Type that should be persisted.

entityType.id UUID

The Entity Type's unique Id.

entityType.insertInstant Long

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

entityType.jwtConfiguration.accessTokenKeyId UUID

The unique id of the signing key used to sign the access token.

entityType.jwtConfiguration.accessTokenVerificationKeyIds Array<UUID> Available since 1.69.0

The list of access token verification key Ids that are trusted for this entity type when entity JWTs are presented to /oauth2/introspect or in SCIM use cases. This list always implicitly includes entityType.jwtConfiguration.accessTokenKeyId.

entityType.jwtConfiguration.enabled Boolean

Indicates if this application is using the JWT configuration defined here.

entityType.jwtConfiguration.timeToLiveInSeconds Integer

The length of time in seconds the JWT will live before it is expired and no longer valid.

entityType.lastUpdateInstant Long

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

entityType.name Long

The name of the entity type (i.e. "Customer" or "Email_Service").

entityType.permissions Array

An array of Permission objects.

entityType.permissions[x].data Object

An object that can hold any information about the Permission that should be persisted.

entityType.permissions[x].description String

A description of the Permission.

entityType.permissions[x].id UUID

The Id of the Permission.

entityType.permissions[x].insertInstant Long

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

entityType.permissions[x].isDefault Boolean

Whether or not the Permission is default. A default Permission is automatically assigned to an Entity if no permissions are provided.

entityType.permissions[x].lastUpdateInstant Long

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

entityType.permissions[x].name String

The name of the Permission.

Example Response JSON for a Single Entity Type

{
  "entityType": {
    "data": {
      "createdBy": "jared@fusionauth.io"
    },
    "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
    "insertInstant": 1595361142909,
    "jwtConfiguration": {
      "accessTokenKeyId": "a7516c7c-6234-4021-b0b4-8870c807aeb2",
      "accessTokenVerificationKeyIds": [
        "f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454"
      ],
      "enabled": true,
      "timeToLiveInSeconds": 3600
    },
    "lastUpdateInstant": 1595361143101,
    "name": "Customer",
    "permissions": [
      {
        "data": {
          "foo": "bar"
        },
        "id": "ce485a91-906f-4615-af75-81d37dc71e90",
        "insertInstant": 1595361142909,
        "isDefault": false,
        "lastUpdateInstant": 1595361143101,
        "name": "admin"
      },
      {
        "id": "ce485a91-906f-4615-af75-81d37dc71e91",
        "isDefault": true,
        "insertInstant": 1595361142911,
        "lastUpdateInstant": 1595361143111,
        "name": "user"
      }
    ]
  }
}

Retrieve an Entity Type#

This API is used to retrieve one or all of the configured Entity Types. Specifying an Id on the URI will retrieve a single Entity Type. Leaving off the Id will retrieve all of the Entity Types.

Request#

Global API Key Authentication
Retrieve all of the Entity Types
GET/api/entity/type
OpenAPI Spec
Global API Key Authentication
Retrieve a single Entity Type by Id
GET/api/entity/type/{entityTypeId}
OpenAPI Spec

Request Parameters#

entityTypeId UUID optional

The Id of the Entity Type to retrieve.

Response#

The response for this API contains either a single Entity Type or all of the Entity Types. When you call this API with an Id the response will contain just that Entity Type. When you call this API without an Id the response will contain all of the Entity Types. Both response types are defined below along with an example JSON response.

Response Codes
CodeDescription
200The request was successful. The response will contain a JSON body.
401You 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.
404The object you requested doesn't exist. The response will be empty.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body#

entityType.data Object

An object that can hold any information about the Entity Type that should be persisted.

entityType.id UUID

The Entity Type's unique Id.

entityType.insertInstant Long

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

entityType.jwtConfiguration.accessTokenKeyId UUID

The unique id of the signing key used to sign the access token.

entityType.jwtConfiguration.accessTokenVerificationKeyIds Array<UUID> Available since 1.69.0

The list of access token verification key Ids that are trusted for this entity type when entity JWTs are presented to /oauth2/introspect or in SCIM use cases. This list always implicitly includes entityType.jwtConfiguration.accessTokenKeyId.

entityType.jwtConfiguration.enabled Boolean

Indicates if this application is using the JWT configuration defined here.

entityType.jwtConfiguration.timeToLiveInSeconds Integer

The length of time in seconds the JWT will live before it is expired and no longer valid.

entityType.lastUpdateInstant Long

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

entityType.name Long

The name of the entity type (i.e. "Customer" or "Email_Service").

entityType.permissions Array

An array of Permission objects.

entityType.permissions[x].data Object

An object that can hold any information about the Permission that should be persisted.

entityType.permissions[x].description String

A description of the Permission.

entityType.permissions[x].id UUID

The Id of the Permission.

entityType.permissions[x].insertInstant Long

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

entityType.permissions[x].isDefault Boolean

Whether or not the Permission is default. A default Permission is automatically assigned to an Entity if no permissions are provided.

entityType.permissions[x].lastUpdateInstant Long

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

entityType.permissions[x].name String

The name of the Permission.

Example Response JSON for a Single Entity Type

{
  "entityType": {
    "data": {
      "createdBy": "jared@fusionauth.io"
    },
    "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
    "insertInstant": 1595361142909,
    "jwtConfiguration": {
      "accessTokenKeyId": "a7516c7c-6234-4021-b0b4-8870c807aeb2",
      "accessTokenVerificationKeyIds": [
        "f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454"
      ],
      "enabled": true,
      "timeToLiveInSeconds": 3600
    },
    "lastUpdateInstant": 1595361143101,
    "name": "Customer",
    "permissions": [
      {
        "data": {
          "foo": "bar"
        },
        "id": "ce485a91-906f-4615-af75-81d37dc71e90",
        "insertInstant": 1595361142909,
        "isDefault": false,
        "lastUpdateInstant": 1595361143101,
        "name": "admin"
      },
      {
        "id": "ce485a91-906f-4615-af75-81d37dc71e91",
        "isDefault": true,
        "insertInstant": 1595361142911,
        "lastUpdateInstant": 1595361143111,
        "name": "user"
      }
    ]
  }
}

Response Body#

entityTypes[x] Array

The list of EntityType objects.

entityTypes[x].data Object

An object that can hold any information about the Entity Type that should be persisted.

entityTypes[x].id UUID

The Entity Type's unique Id.

entityTypes[x].insertInstant Long

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

entityTypes[x].jwtConfiguration.accessTokenKeyId UUID

The unique id of the signing key used to sign the access token.

entityTypes[x].jwtConfiguration.accessTokenVerificationKeyIds Array<UUID> Available since 1.69.0

The list of access token verification key Ids that are trusted for this entity type when entity JWTs are presented to /oauth2/introspect or in SCIM use cases. This list always implicitly includes entityType.jwtConfiguration.accessTokenKeyId.

entityTypes[x].jwtConfiguration.enabled Boolean

Indicates if this application is using the JWT configuration defined here.

entityTypes[x].jwtConfiguration.timeToLiveInSeconds Integer

The length of time in seconds the JWT will live before it is expired and no longer valid.

entityTypes[x].lastUpdateInstant Long

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

entityTypes[x].name Long

The name of the entity type (i.e. "Customer" or "Email_Service").

entityTypes[x].permissions Array

An array of Permission objects.

entityTypes[x].permissions[x].data Object

An object that can hold any information about the Permission that should be persisted.

entityTypes[x].permissions[x].description String

A description of the Permission.

entityTypes[x].permissions[x].id UUID

The Id of the Permission.

entityTypes[x].permissions[x].insertInstant Long

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

entityTypes[x].permissions[x].isDefault Boolean

Whether or not the Permission is default. A default Permission is automatically assigned to an Entity if no permissions are provided.

entityTypes[x].permissions[x].lastUpdateInstant Long

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

entityTypes[x].permissions[x].name String

The name of the Permission.

Example Response JSON for all Entity Types

{
  "entityTypes": [
    {
      "entityType": {
        "data": {
          "createdBy": "jared@fusionauth.io"
        },
        "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
        "insertInstant": 1595361142909,
        "jwtConfiguration": {
          "accessTokenKeyId": "a7516c7c-6234-4021-b0b4-8870c807aeb2",
          "accessTokenVerificationKeyIds": [
            "f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454"
          ],
          "enabled": true,
          "timeToLiveInSeconds": 3600
        },
        "lastUpdateInstant": 1595361143101,
        "name": "Customer",
        "permissions": [
          {
            "data": {
              "foo": "bar"
            },
            "id": "ce485a91-906f-4615-af75-81d37dc71e90",
            "insertInstant": 1595361142909,
            "isDefault": false,
            "lastUpdateInstant": 1595361143101,
            "name": "admin"
          },
          {
            "id": "ce485a91-906f-4615-af75-81d37dc71e91",
            "isDefault": true,
            "insertInstant": 1595361142911,
            "lastUpdateInstant": 1595361143111,
            "name": "user"
          }
        ]
      }
    }
  ]
}

Update an Entity Type#

This API is used to update an existing Entity Type.

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

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

Request#

Global API Key Authentication
Update an Entity Type by Id
PUT/api/entity/type/{entityTypeId}
OpenAPI Spec
PATCH/api/entity/type/{entityTypeId}
OpenAPI Spec
note

For backward compatibility, the PATCH method accepts the same media type (specified by a Content-Type of application/json) and body as the PUT request. You can also use the following media types for different behavior:

For details, see the PATCH documentation.

Using a media type of application/json merges the provided request parameters into the existing object. As a result, all parameters are optional with PATCH: only provide the values you want to change. To remove a value, provide a null value. Patching an Array appends all values in the new list to the old list.

Request Parameters#

entityTypeId UUID required

The Id of the Entity Type to update.

Request Body#

entityType.data Object optional

An object that can hold any information about the Entity Type that should be persisted.

entityType.jwtConfiguration.accessTokenKeyId UUID optional

The unique id of the signing key used to sign the access token.

Required when enabled is set to true.

entityType.jwtConfiguration.accessTokenVerificationKeyIds Array<UUID> optional Available since 1.69.0

The list of access token verification key Ids that are trusted for this entity type when entity JWTs are presented to /oauth2/introspect or in SCIM use cases. This list always implicitly includes entityType.jwtConfiguration.accessTokenKeyId.

Facilitates key rotation by trusting multiple keys: if you change entityType.jwtConfiguration.accessTokenKeyId to a new key and supply the previous key in this field, FusionAuth will trust JWTs signed by both keys, while only signing JWTs with the new key.

entityType.jwtConfiguration.enabled Boolean optional Defaults to false

Indicates if this application is using the JWT configuration defined here or the global JWT configuration defined by the Tenant. If this is false the signing algorithm configured in the Tenant will be used. If true the signing algorithm defined in this application will be used.

entityType.jwtConfiguration.timeToLiveInSeconds Integer optional

The length of time in seconds the JWT will live before it is expired and no longer valid.

Required when enabled is set to true.

entityType.name String required

A descriptive name for the entity type (i.e. "Customer" or "Email_Service").

Example Request JSON

{
  "entityType": {
    "name": "Customer",
    "data": {
      "createdBy": "jared@fusionauth.io"
    },
    "jwtConfiguration": {
      "accessTokenKeyId": "a7516c7c-6234-4021-b0b4-8870c807aeb2",
      "accessTokenVerificationKeyIds": [
        "f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454"
      ],
      "enabled": true,
      "timeToLiveInSeconds": 3600
    }
  }
}

Response#

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

Response Codes
CodeDescription
200The request was successful. The response will contain a JSON body.
400The 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.
401You 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.
404The object you are trying to update doesn't exist. The response will be empty.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body#

entityType.data Object

An object that can hold any information about the Entity Type that should be persisted.

entityType.id UUID

The Entity Type's unique Id.

entityType.insertInstant Long

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

entityType.jwtConfiguration.accessTokenKeyId UUID

The unique id of the signing key used to sign the access token.

entityType.jwtConfiguration.accessTokenVerificationKeyIds Array<UUID> Available since 1.69.0

The list of access token verification key Ids that are trusted for this entity type when entity JWTs are presented to /oauth2/introspect or in SCIM use cases. This list always implicitly includes entityType.jwtConfiguration.accessTokenKeyId.

entityType.jwtConfiguration.enabled Boolean

Indicates if this application is using the JWT configuration defined here.

entityType.jwtConfiguration.timeToLiveInSeconds Integer

The length of time in seconds the JWT will live before it is expired and no longer valid.

entityType.lastUpdateInstant Long

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

entityType.name Long

The name of the entity type (i.e. "Customer" or "Email_Service").

entityType.permissions Array

An array of Permission objects.

entityType.permissions[x].data Object

An object that can hold any information about the Permission that should be persisted.

entityType.permissions[x].description String

A description of the Permission.

entityType.permissions[x].id UUID

The Id of the Permission.

entityType.permissions[x].insertInstant Long

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

entityType.permissions[x].isDefault Boolean

Whether or not the Permission is default. A default Permission is automatically assigned to an Entity if no permissions are provided.

entityType.permissions[x].lastUpdateInstant Long

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

entityType.permissions[x].name String

The name of the Permission.

Example Response JSON for a Single Entity Type

{
  "entityType": {
    "data": {
      "createdBy": "jared@fusionauth.io"
    },
    "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
    "insertInstant": 1595361142909,
    "jwtConfiguration": {
      "accessTokenKeyId": "a7516c7c-6234-4021-b0b4-8870c807aeb2",
      "accessTokenVerificationKeyIds": [
        "f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454"
      ],
      "enabled": true,
      "timeToLiveInSeconds": 3600
    },
    "lastUpdateInstant": 1595361143101,
    "name": "Customer",
    "permissions": [
      {
        "data": {
          "foo": "bar"
        },
        "id": "ce485a91-906f-4615-af75-81d37dc71e90",
        "insertInstant": 1595361142909,
        "isDefault": false,
        "lastUpdateInstant": 1595361143101,
        "name": "admin"
      },
      {
        "id": "ce485a91-906f-4615-af75-81d37dc71e91",
        "isDefault": true,
        "insertInstant": 1595361142911,
        "lastUpdateInstant": 1595361143111,
        "name": "user"
      }
    ]
  }
}

Delete an Entity Type#

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

Request#

Global API Key Authentication
Delete an Entity Type By Id
DELETE/api/entity/type/{entityTypeId}
OpenAPI Spec

Request Parameters#

entityTypeId UUID required

The Id of the Entity Type to delete.

Response#

This API does not return a JSON response body.

Response Codes
CodeDescription
200The request was successful.
400The 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.
401You 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.
404The object you requested doesn't exist. The response will be empty.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Search for an Entity Type#

This API is used to search for matching Entity Types.

Request#

Global API Key Authentication
Search Entity Types
GET/api/entity/type/search?name={name}
OpenAPI Spec

Request Parameters#

name String required

The name of the Entity Type for which to search.

The search matches against the name field and any entity type matching. 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.

numberOfResults Integer optional Defaults to 25

The number of results to return from the search.

orderBy String optional Defaults to name ASC

The database column to order the search results on plus the order direction.

The columns you can use for this are:

  • insertInstant - the instant when the Entity Type was created
  • lastUpdateInstant - the instant when the Entity Type was last updated
  • name - the name of the Entity Type

For example, to order the results by the insert instant in a descending order, the value would be provided as insertInstant DESC. The final string is optional can be set to ASC or DESC.

startRow Integer optional Defaults to 0

The offset into the total results. In order to paginate the results, increment this value by the numberOfResults for subsequent requests.

Response#

The response for this API contains the Entity Type matching the search criteria in paginated format.

Response Codes
CodeDescription
200The request was successful. The response will contain a JSON body.
401You 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.
404The object you requested doesn't exist. The response will be empty.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body#

entityTypes[x] Array

The list of EntityType objects.

entityTypes[x].data Object

An object that can hold any information about the Entity Type that should be persisted.

entityTypes[x].id UUID

The Entity Type's unique Id.

entityTypes[x].insertInstant Long

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

entityTypes[x].jwtConfiguration.accessTokenKeyId UUID

The unique id of the signing key used to sign the access token.

entityTypes[x].jwtConfiguration.accessTokenVerificationKeyIds Array<UUID> Available since 1.69.0

The list of access token verification key Ids that are trusted for this entity type when entity JWTs are presented to /oauth2/introspect or in SCIM use cases. This list always implicitly includes entityType.jwtConfiguration.accessTokenKeyId.

entityTypes[x].jwtConfiguration.enabled Boolean

Indicates if this application is using the JWT configuration defined here.

entityTypes[x].jwtConfiguration.timeToLiveInSeconds Integer

The length of time in seconds the JWT will live before it is expired and no longer valid.

entityTypes[x].lastUpdateInstant Long

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

entityTypes[x].name Long

The name of the entity type (i.e. "Customer" or "Email_Service").

entityTypes[x].permissions Array

An array of Permission objects.

entityTypes[x].permissions[x].data Object

An object that can hold any information about the Permission that should be persisted.

entityTypes[x].permissions[x].description String

A description of the Permission.

entityTypes[x].permissions[x].id UUID

The Id of the Permission.

entityTypes[x].permissions[x].insertInstant Long

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

entityTypes[x].permissions[x].isDefault Boolean

Whether or not the Permission is default. A default Permission is automatically assigned to an Entity if no permissions are provided.

entityTypes[x].permissions[x].lastUpdateInstant Long

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

entityTypes[x].permissions[x].name String

The name of the Permission.

Example Response JSON for all Entity Types

{
  "entityTypes": [
    {
      "entityType": {
        "data": {
          "createdBy": "jared@fusionauth.io"
        },
        "id": "8174f72f-5ecd-4eae-8de8-7fef597b3473",
        "insertInstant": 1595361142909,
        "jwtConfiguration": {
          "accessTokenKeyId": "a7516c7c-6234-4021-b0b4-8870c807aeb2",
          "accessTokenVerificationKeyIds": [
            "f8c3de3d-1fea-4d7c-a8b0-29f63c4c3454"
          ],
          "enabled": true,
          "timeToLiveInSeconds": 3600
        },
        "lastUpdateInstant": 1595361143101,
        "name": "Customer",
        "permissions": [
          {
            "data": {
              "foo": "bar"
            },
            "id": "ce485a91-906f-4615-af75-81d37dc71e90",
            "insertInstant": 1595361142909,
            "isDefault": false,
            "lastUpdateInstant": 1595361143101,
            "name": "admin"
          },
          {
            "id": "ce485a91-906f-4615-af75-81d37dc71e91",
            "isDefault": true,
            "insertInstant": 1595361142911,
            "lastUpdateInstant": 1595361143111,
            "name": "user"
          }
        ]
      }
    }
  ]
}

Create an Entity Type Permission#

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

Request#

Global API Key Authentication
Create a Permission with a randomly generated Id
POST/api/entity/type/{entityTypeId}/permission
OpenAPI Spec
Global API Key Authentication
Create a Permission with a given Id
POST/api/entity/type/{entityTypeId}/permission/{permissionId}
OpenAPI Spec

Request Parameters#

entityTypeId UUID required

The Id of the Entity Type.

permissionId UUID optional Defaults to secure random UUID

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

Request Body#

permission.data Object optional

An object that can hold any information about the Permission that should be persisted.

permission.description String optional

The description of the Permission.

permission.isDefault Boolean optional Defaults to false

Whether or not the Permission is a default permission. A default permission is automatically granted to an entity of this type if no permissions are provided in a grant request.

permission.name String required

The name of the Permission. Once created, this field cannot be changed.

Example Request JSON

{
  "permission": {
    "data": {
      "foo": "bar"
    },
    "description": "The permission description",
    "isDefault": true,
    "name": "read"
  }
}

Response#

The response for this API contains the information for the permission that was created.

Response Codes
CodeDescription
200The request was successful. The response will contain a JSON body.
400The 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.
401You 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.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body#

permission.data Object

An object that can hold any information about the Permission that should be persisted.

permission.description String

The description of the Permission.

permission.id UUID

The Id of the Permission.

permission.isDefault Boolean

Whether or not the Permission is a default permission. A default permission is automatically granted to an entity of this type if no permissions are provided in a grant request.

permission.insertInstant Long

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

permission.lastUpdateInstant Long

The instant that the Permission was updated in the FusionAuth database.

permission.name String

The name of the Permission. Once created, this field cannot be changed.

Example Response JSON

{
  "permission": {
    "data": {
      "foo": "bar"
    },
    "description": "The permission description",
    "id": "ce485a91-906f-4615-af75-81d37dc71e90",
    "insertInstant": 1595361142909,
    "isDefault": true,
    "lastUpdateInstant": 1595361143101,
    "name": "read"
  }
}

Update an Entity Type Permission#

This API is used to update an existing Entity Type permission. You must specify the Entity Type Id and the permission Id on the URI to identify the permission that is being updated.

Request#

Global API Key Authentication
Update an Entity Type Permission by Id
PUT/api/entity/type/{entityTypeId}/permission/{permissionId}
OpenAPI Spec
PATCH/api/entity/type/{entityTypeId}/permission/{permissionId}
OpenAPI Spec
note

For backward compatibility, the PATCH method accepts the same media type (specified by a Content-Type of application/json) and body as the PUT request. You can also use the following media types for different behavior:

For details, see the PATCH documentation.

Using a media type of application/json merges the provided request parameters into the existing object. As a result, all parameters are optional with PATCH: only provide the values you want to change. To remove a value, provide a null value. Patching an Array appends all values in the new list to the old list.

Request Parameters#

entityTypeId UUID required

The Id of the Entity Type.

permissionId UUID required

The Id of the permission that is being updated.

Request Body#

permission.data Object optional

An object that can hold any information about the Permission that should be persisted.

permission.description String optional

The description of the Permission.

permission.isDefault Boolean optional Defaults to false

Whether or not the Permission is a default permission. A default permission is automatically granted to an entity of this type if no permissions are provided in a grant request.

Example Request JSON

{
  "permission": {
    "data": {
      "foo": "bar"
    },
    "description": "The permission description",
    "isDefault": true
  }
}

Response#

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

Response Codes
CodeDescription
200The request was successful. The response will contain a JSON body.
400The 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.
401You 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.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body#

permission.data Object

An object that can hold any information about the Permission that should be persisted.

permission.description String

The description of the Permission.

permission.id UUID

The Id of the Permission.

permission.isDefault Boolean

Whether or not the Permission is a default permission. A default permission is automatically granted to an entity of this type if no permissions are provided in a grant request.

permission.insertInstant Long

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

permission.lastUpdateInstant Long

The instant that the Permission was updated in the FusionAuth database.

permission.name String

The name of the Permission. Once created, this field cannot be changed.

Example Response JSON

{
  "permission": {
    "data": {
      "foo": "bar"
    },
    "description": "The permission description",
    "id": "ce485a91-906f-4615-af75-81d37dc71e90",
    "insertInstant": 1595361142909,
    "isDefault": true,
    "lastUpdateInstant": 1595361143101,
    "name": "read"
  }
}

Delete an Entity Type Permission#

This API is used to delete a permission from an Entity Type.

Request#

Global API Key Authentication
Delete an Entity Type Permission by Id
DELETE/api/entity/type/{entityTypeId}/permission/{permissionId}
OpenAPI Spec

Request Parameters#

entityTypeId UUID required

The Id of the Entity Type the permission belongs.

permissionId UUID required

The Id of the permission to delete.

Global API Key Authentication
Delete an Entity Type Permission by name
DELETE/api/entity/type/{entityTypeId}/permission?name={name}

Request Parameters#

entityTypeId UUID required

The Id of the Entity Type the permission belongs.

name String required

The name of the permission to delete.

Response#

This API does not return a JSON response body.

Response Codes
CodeDescription
200The request was successful.
400The 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.
401You 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.
404The object you requested doesn't exist. The response will be empty.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.