> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt)

# Grant API

Learn about the APIs for granting and revoking permissions to entities.

This feature is only available in paid plans. To learn more, see [our pricing page](https://fusionauth.io/pricing.md).

This page contains the APIs for granting and revoking permissions to Entities.

> **VERSION:** Aailable since `1.26.0`

## Grant a User or Entity Permissions to an Entity

This API is used to grant permissions to an Entity for a User or another Entity.

This is an upsert operation. If the grant to this Entity for the specified User or recipient Entity exists, it will be updated. Otherwise it will be created.

### Request

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Create a Grant

`POST /api/entity/{entityId}/grant`

#### Request Parameters

`entityId`

*   UUID
*   required

The Id of the Entity to which access is granted.

#### 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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

#### Request Body

`grant.data`

*   Object

An object that can hold any information about the Grant that should be persisted. Please review the [limits on data field types](https://fusionauth.io/docs/get-started/core-concepts/limitations.md#data-type-changes-in-data-fields) as you plan for and build your custom data schema.

`grant.permissions`

*   Array<String>
*   optional

The set of permissions of this Grant.

`grant.recipientEntityId`

*   UUID
*   optional

The Entity Id for which access is granted.

If **recipientEntityId** is not provided, then the **userId** will be required.

`grant.userId`

*   UUID
*   optional

The User Id for which access is granted.

If **userId** is not provided, then the **recipientEntityId** will be required.

*Example User Grant Request JSON*

```json
{
  "grant": {
    "data": {
      "expiresAt": 1695361142909
    },
    "permissions": [
      "read",
      "write",
      "sue"
    ],
    "userId": "7174f72f-5ecd-4eae-8de8-7fef597b3473"
  }
}
```

*Example Grant Request JSON*

```json
{
  "grant": {
    "data": {
      "foo": "bar"
    },
    "permissions": [
      "read",
      "write",
      "sue"
    ],
    "recipientEntityId": "5174f72f-5ecd-4eae-8de8-7fef597b3473"
  }
}
```

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Update a Grant

`PUT /api/entity/{entityId}/grant`

#### Request Parameters

`entityId`

*   UUID
*   required

The Id of the Entity to which access is granted.

#### 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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

#### Request Body

`grant.data`

*   Object

An object that can hold any information about the Grant that should be persisted. Please review the [limits on data field types](https://fusionauth.io/docs/get-started/core-concepts/limitations.md#data-type-changes-in-data-fields) as you plan for and build your custom data schema.

`grant.permissions`

*   Array<String>
*   optional

The set of permissions of this Grant.

`grant.recipientEntityId`

*   UUID
*   optional

The Entity Id for which access is granted.

If **recipientEntityId** is not provided, then the **userId** will be required.

`grant.userId`

*   UUID
*   optional

The User Id for which access is granted.

If **userId** is not provided, then the **recipientEntityId** will be required.

*Example User Grant Request JSON*

```json
{
  "grant": {
    "data": {
      "expiresAt": 1695361142909
    },
    "permissions": [
      "read",
      "write",
      "sue"
    ],
    "userId": "7174f72f-5ecd-4eae-8de8-7fef597b3473"
  }
}
```

*Example Grant Request JSON*

```json
{
  "grant": {
    "data": {
      "foo": "bar"
    },
    "permissions": [
      "read",
      "write",
      "sue"
    ],
    "recipientEntityId": "5174f72f-5ecd-4eae-8de8-7fef597b3473"
  }
}
```

### Response

This API does not return a JSON response body.

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. |
| 400 | The request was invalid and/or malformed. The response will contain an [Errors](https://fusionauth.io/docs/apis/errors.md) 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](https://fusionauth.io/docs/apis/authentication.md). |
| 404 | The Entity to which access is being granted was not found. |
| 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. |

## Retrieve Grants

This API is used to retrieve Grants. Specifying only an **entityId** on the URI will retrieve all Grants for a single Entity.

Adding a parameter of **userId** or **recipientEntityId** filters the returned Grants. It limits them to those made to the User or recipient Entity, respectively.

### Request

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Retrieve All Grants To This Entity

`GET /api/entity/{entityId}/grant`

#### 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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Retrieve Grants To This Entity For a User

`GET /api/entity/{entityId}/grant?userId={userId}?userId={userId}`

#### Request Parameters

`entityId`

*   UUID
*   required

The Id of the Entity to which access is granted.

`userId`

*   UUID
*   required

The Id of the User which has been granted access.

#### 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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Retrieve Grants For Another Entity

`GET /api/entity/{entityId}/grant?recipientEntityId={recipientEntityId}?recipientEntityId={recipientEntityId}`

#### Request Parameters

`entityId`

*   UUID
*   required

The Id of the Entity to which access is granted.

`recipientEntityId`

*   UUID
*   required

The Id of the Entity which has been granted access.

#### 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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

### Response

This API is used to retrieve one or all of the Grants made to this Entity. Specifying only an **entityId** on the URI will retrieve all Grants. Adding a parameter of **userId** or **recipientEntityId** will retrieve a single Grant made to the User or Entity, respectively.

*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](https://fusionauth.io/docs/apis/errors.md) 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](https://fusionauth.io/docs/apis/authentication.md). |
| 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

`grant.data`

*   Object

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

`grant.entity`

*   Object

The Entity to which access is granted. See the [Entity API](https://fusionauth.io/docs/apis/entities/entities.md) for property definitions and example JSON.

`grant.id`

*   UUID

The unique Id of the Grant.

`grant.insertInstant`

*   Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Grant was added to the FusionAuth database.

`grant.lastUpdateInstant`

*   Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Grant was last updated in the FusionAuth database.

`grant.permission`

*   Array<String>

The set of permissions of this Grant.

`grant.recipientEntityId`

*   UUID

The Entity Id for which access is granted.

`grant.userId`

*   UUID

The User Id for which access is granted.

`total`

*   Long

The total number of results for the search. This can be used for pagination.

*Example Response JSON for a Single Grant*

```json
{
  "grant": {
    "data": {
      "foo": "bar"
    },
    "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"
      }
    },
    "id": "8174f72f-5ecd-4eae-8de8-6fef597b3473",
    "insertInstant": 1595361142929,
    "lastUpdateInstant": 1595361143121,
    "permissions": [
      "read",
      "write",
      "sue"
    ],
    "userId": "7174f72f-5ecd-4eae-8de8-7fef597b3473"
  }
}
```

#### Response Body

`grants[x]`

*   Array

The list of Grant objects.

`grants[x].data`

*   Object

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

`grants[x].entity`

*   Object

The Entity to which access is granted. See the [Entity API](https://fusionauth.io/docs/apis/entities/entities.md) for property definitions and example JSON.

`grants[x].id`

*   UUID

The unique Id of the Grant.

`grants[x].insertInstant`

*   Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Grant was added to the FusionAuth database.

`grants[x].lastUpdateInstant`

*   Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Grant was last updated in the FusionAuth database.

`grants[x].permission`

*   Array<String>

The set of permissions of this Grant.

`grants[x].recipientEntityId`

*   UUID

The Entity Id for which access is granted.

`grants[x].userId`

*   UUID

The User Id for which access is granted.

`total`

*   Long

The total number of results for the search. This can be used for pagination.

*Example Response JSON for Multiple Grants*

```json
{
  "grants": [
    {
      "data": {
        "foo": "bar"
      },
      "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"
        }
      },
      "id": "8174f72f-5ecd-4eae-8de8-6fef597b3473",
      "insertInstant": 1595361142929,
      "lastUpdateInstant": 1595361143121,
      "permissions": [
        "read",
        "write",
        "sue"
      ],
      "userId": "7174f72f-5ecd-4eae-8de8-7fef597b3473"
    }
  ]
}
```

## Delete a Grant

This API is used to delete a Grant from an Entity. This is also known as revoking the Grant.

### Request

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Delete a Grant for a User

`DELETE /api/entity/{entityId}/grant?userId={userId}?userId={userId}`

#### Request Parameters

`entityId`

*   UUID
*   required

The Id of the Entity which is the target of the Grant.

`userId`

*   UUID
*   required

The Id of the User who received the Grant.

#### 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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

[API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Delete a Grant for a Recipient Entity

`DELETE /api/entity/{entityId}/grant?recipientEntityId={recipientEntityId}?recipientEntityId={recipientEntityId}`

#### Request Parameters

`entityId`

*   UUID
*   required

The Id of the Entity which is the target of the Grant.

`recipientEntityId`

*   UUID
*   required

The Id of the Entity which received the Grant.

#### 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](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

### Response

This API does not return a JSON response body.

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. |
| 400 | The request was invalid and/or malformed. The response will contain an [Errors](https://fusionauth.io/docs/apis/errors.md) 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](https://fusionauth.io/docs/apis/authentication.md). |
| 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. |

## Search for Grants

This API is used to search for Entity Grants. 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

[Global API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#global-api-key-authentication)

Search for Grants by Entity Id

`GET /api/entity/grant/search?entityId={uuid}?entityId={uuid}`

[Global API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#global-api-key-authentication)

Search for Grants by Entity name

`GET /api/entity/grant/search?name={string}?name={string}`

[Global API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#global-api-key-authentication)

Search for Grants by User Id

`GET /api/entity/grant/search?userId={uuid}?userId={uuid}`

#### Request Parameters

`entityId`

*   UUID
*   optional

An Entity Id to search for Grants on.

`name`

*   String
*   optional

The name of the Entity that the Grants are for. For example, if you want the Grants for "Jane's Thermostat", you can specify that as the name parameter to receive the Grants for that Entity.

It is recommended that you use this parameter in conjunction with the **entityId** or the **userId** parameter. This will help reduce the set of Grants to be queried in the database and dramatically reduce the overhead of the search.

`numberOfResults`

*   Integer
*   optional
*   Defaults to 25

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

`startRow`

*   Integer
*   optional
*   Defaults to 0

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

`orderBy`

*   String
*   optional
*   Defaults to name ASC

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

The possible values are:

*   `insertInstant` - the [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the Entity Grant was created
*   `name` - the name of the Entity the Grant is for

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

`userId`

*   UUID
*   optional

A User Id to search for Grants on.

[Global API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#global-api-key-authentication)

Search for Grants using a JSON request body.

`POST /api/entity/grant/search`

#### Request Body

`search.entityId`

*   UUID
*   optional

An Entity Id to search for Grants on.

`search.name`

*   String
*   optional

The name of the Entity that the Grants are for. For example, if you want the Grants for "Jane's Thermostat", you can specify that as the name parameter to receive the Grants for that Entity.

It is recommended that you use this parameter in conjunction with the **entityId** or the **userId** parameter. This will help reduce the set of Grants to be queried in the database and dramatically reduce the overhead of the search.

`search.numberOfResults`

*   Integer
*   optional
*   Defaults to 25

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

`search.startRow`

*   Integer
*   optional
*   Defaults to 0

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

`search.orderBy`

*   String
*   optional
*   Defaults to name ASC

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

The possible values are:

*   `insertInstant` - the [instant](https://fusionauth.io/docs/reference/data-types.md#instants) when the Entity Grant was created
*   `name` - the name of the Entity the Grant is for

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

`search.userId`

*   UUID
*   optional

A User Id to search for Grants on.

##### Request Body Examples

*Example Request JSON*

```json
{
  "search": {
    "entityId": "e4b44fdc-cee6-46f2-8b31-93c4d91d92b3",
    "numberOfResults": 25,
    "name": "Jane's Thermostat",
    "orderBy": "name DESC",
    "startRow": 0,
    "userId": "dc7f68e9-2731-484d-a5be-cd1fd73b8763"
  }
}
```

### Response

The response contains the Entity Grant objects that were found as part of the lookup or search.

*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](https://fusionauth.io/docs/apis/errors.md) 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](https://fusionauth.io/docs/apis/authentication.md). |
| 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

`grants[x]`

*   Array

The list of Grant objects.

`grants[x].data`

*   Object

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

`grants[x].entity`

*   Object

The Entity to which access is granted. See the [Entity API](https://fusionauth.io/docs/apis/entities/entities.md) for property definitions and example JSON.

`grants[x].id`

*   UUID

The unique Id of the Grant.

`grants[x].insertInstant`

*   Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Grant was added to the FusionAuth database.

`grants[x].lastUpdateInstant`

*   Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Grant was last updated in the FusionAuth database.

`grants[x].permission`

*   Array<String>

The set of permissions of this Grant.

`grants[x].recipientEntityId`

*   UUID

The Entity Id for which access is granted.

`grants[x].userId`

*   UUID

The User Id for which access is granted.

`total`

*   Long

The total number of results for the search. This can be used for pagination.

*Example Response JSON for Multiple Grants*

```json
{
  "grants": [
    {
      "data": {
        "foo": "bar"
      },
      "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"
        }
      },
      "id": "8174f72f-5ecd-4eae-8de8-6fef597b3473",
      "insertInstant": 1595361142929,
      "lastUpdateInstant": 1595361143121,
      "permissions": [
        "read",
        "write",
        "sue"
      ],
      "userId": "7174f72f-5ecd-4eae-8de8-7fef597b3473"
    }
  ]
}
```