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

    Grant 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 granting and revoking permissions to Entities.

    This API has been available since 1.26.0

    • Grant a User or Entity Permissions to an Entity

    • Retrieve Grants

    • Delete a Grant

    • Search for Grants

    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

    Create a Grant

    URI

    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 for additional information.

    Update a Grant

    URI

    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 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 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
    
    {
      "grant": {
        "data": {
          "expiresAt": 1695361142909
        },
        "permissions": [
          "read",
          "write",
          "sue"
        ],
        "userId": "7174f72f-5ecd-4eae-8de8-7fef597b3473"
      }
    }
    Example Grant Request 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.

    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.

    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

    Retrieve All Grants To This Entity

    URI

    GET /api/entity/{entityId}/grant

    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

    Retrieve Grants To This Entity For a User

    URI

    GET /api/entity/{entityId}/grant?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 for additional information.

    Retrieve Grants For Another Entity

    URI

    GET /api/entity/{entityId}/grant?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 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.

    Table 2. Response Codes
    Code Description

    200

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

    400

    The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.

    401

    You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

    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 target Entity of this Grant. Consult the Entity documentation for more details about the fields of this object.

    grant.id [UUID]

    The unique Id of the Grant.

    grant.insertInstant [Long]

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

    grant.lastUpdateInstant [Long]

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

    grant.permissions [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.

    Example Response JSON for a Single Grant
    
    {
      "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 target Entity of this Grant. Consult the Entity documentation for more details about the fields of this object.

    grants[x].id [UUID]

    The unique Id of the Grant.

    grants[x].insertInstant [Long]

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

    grants[x].lastUpdateInstant [Long]

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

    grants[x].permissions [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.

    Example Response JSON for Multiple Grants
    
    {
      "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

    Delete a Grant for a User

    URI

    DELETE /api/entity/{entityId}/grant?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 for additional information.

    Delete a Grant for a Recipient Entity

    URI

    DELETE /api/entity/{entityId}/grant?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 for additional information.

    Response

    This API does not return a JSON response body.

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

    Search for Grants by Entity Id

    URI

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

    Search for Grants by Entity name

    URI

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

    Search for Grants by User Id

    URI

    GET /api/entity/grant/search?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 columns you can use for this are:

    • insertInstant - the instant 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.

    Search for Grants using a JSON request body.

    URI

    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 columns you can use for this are:

    • insertInstant - the instant 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
    
    {
      "search": {
        "entityId": "e4b44fdc-cee6-46f2-8b31-93c4d91d92b3",
        "numberOfResults": 50,
        "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.

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

    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 target Entity of this Grant. Consult the Entity documentation for more details about the fields of this object.

    grants[x].id [UUID]

    The unique Id of the Grant.

    grants[x].insertInstant [Long]

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

    grants[x].lastUpdateInstant [Long]

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

    grants[x].permissions [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
    
    {
      "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"
        }
      ],
      "total": 1
    }

    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