---
title: "UserGrants"
slug: "150-manage-usergrants"
updated: 2025-03-19T17:35:45Z
published: 2025-03-19T17:35:45Z
canonical: "docs.developer.comcast.com/150-manage-usergrants"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.developer.comcast.com/llms.txt
> Use this file to discover all available pages before exploring further.

# UserGrants

**UserGrants Module 1.5.0 | Manage SDK**

## Usage

To use the UserGrants module, you can import it into your project from the Firebolt SDK:

```
import { UserGrants } from '@firebolt-js/manage-sdk'
```

## Overview

A module for managing grants given by the user

## Methods

### app

Get all granted and denied user grants for the given app

```
function app(appId: string): Promise<GrantInfo[]>
```

Parameters:

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| `appId` | `string` | true |  |

Promise resolution:

Capabilities:

| Role | Capability |
| --- | --- |
| uses | xrn:firebolt:capability:grants:state |

#### Examples

Default Example

JavaScript:

```
import { UserGrants } from '@firebolt-js/manage-sdk'

let info = await UserGrants.app('certapp')
console.log(info)
```

Value of `info`:

```
;[
  {
    app: {
      id: 'certapp',
      title: 'Firebolt Certification',
    },
    state: 'granted',
    capability: 'xrn:firebolt:capability:data:app-usage',
    role: 'use',
    lifespan: 'seconds',
    expires: '2022-12-14T20:20:39+00:00',
  },
  {
    app: {
      id: 'certapp',
      title: 'Firebolt Certification',
    },
    state: 'denied',
    capability: 'xrn:firebolt:capability:localization:postal-code',
    role: 'use',
    lifespan: 'appActive',
  },
]
```

**JSON-RPC:**

Request:

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "UserGrants.app",
  "params": {
    "appId": "certapp"
  }
}
```

Response:

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "app": {
        "id": "certapp",
        "title": "Firebolt Certification"
      },
      "state": "granted",
      "capability": "xrn:firebolt:capability:data:app-usage",
      "role": "use",
      "lifespan": "seconds",
      "expires": "2022-12-14T20:20:39+00:00"
    },
    {
      "app": {
        "id": "certapp",
        "title": "Firebolt Certification"
      },
      "state": "denied",
      "capability": "xrn:firebolt:capability:localization:postal-code",
      "role": "use",
      "lifespan": "appActive"
    }
  ]
}
```

---

### capability

Get all granted and denied user grants for the given capability

```
function capability(capability: Capability): Promise<GrantInfo[]>
```

Parameters:

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| `capability` | [`Capability`](/docs/150-manage-Capabilities-schemas#Capability) | true | pattern: ^xrn:firebolt:capability:([a-z0-9-]+)((:[a-z0-9-]+)?)$ |

Promise resolution:

Capabilities:

| Role | Capability |
| --- | --- |
| uses | xrn:firebolt:capability:grants:state |

#### Examples

Default Example

JavaScript:

```
import { UserGrants } from '@firebolt-js/manage-sdk'

let info = await UserGrants.capability(
  'xrn:firebolt:capability:localization:postal-code',
)
console.log(info)
```

Value of `info`:

```
;[
  {
    state: 'granted',
    capability: 'xrn:firebolt:capability:localization:postal-code',
    role: 'use',
    lifespan: 'powerActive',
  },
]
```

**JSON-RPC:**

Request:

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "UserGrants.capability",
  "params": {
    "capability": "xrn:firebolt:capability:localization:postal-code"
  }
}
```

Response:

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "state": "granted",
      "capability": "xrn:firebolt:capability:localization:postal-code",
      "role": "use",
      "lifespan": "powerActive"
    }
  ]
}
```

---

### clear

Clears the grant for a given capability, to a specific app if appropriate. Calling this results in a persisted Denied Grant that lasts for the duration of the Grant Policy lifespan.

```
function clear(
  role: Role,
  capability: Capability,
  options: GrantModificationOptions,
): Promise<void>
```

Parameters:

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | [`Role`](/docs/150-manage-Capabilities-schemas#Role) | true | values: `'use' \| 'manage' \| 'provide'` |
| `capability` | [`Capability`](/docs/150-manage-Capabilities-schemas#Capability) | true | pattern: ^xrn:firebolt:capability:([a-z0-9-]+)((:[a-z0-9-]+)?)$ |
| `options` | [`GrantModificationOptions`](/docs/150-manage-usergrants#grantmodificationoptions) | false |  |

Promise resolution:

Capabilities:

| Role | Capability |
| --- | --- |
| manages | xrn:firebolt:capability:grants:state |

#### Examples

Default Example

JavaScript:

```
import { UserGrants } from '@firebolt-js/manage-sdk'

let result = await UserGrants.clear(
  'use',
  'xrn:firebolt:capability:localization:postal-code',
  { appId: 'certapp' },
)
console.log(result)
```

Value of `result`:

```
null
```

**JSON-RPC:**

Request:

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "UserGrants.clear",
  "params": {
    "role": "use",
    "capability": "xrn:firebolt:capability:localization:postal-code",
    "options": {
      "appId": "certapp"
    }
  }
}
```

Response:

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
```

---

### deny

Denies a given capability, to a specific app if appropriate. Calling this results in a persisted Denied Grant that lasts for the duration of the Grant Policy lifespan.

```
function deny(
  role: Role,
  capability: Capability,
  options: GrantModificationOptions,
): Promise<void>
```

Parameters:

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | [`Role`](/docs/150-manage-Capabilities-schemas#Role) | true | values: `'use' \| 'manage' \| 'provide'` |
| `capability` | [`Capability`](/docs/150-manage-Capabilities-schemas#Capability) | true | pattern: ^xrn:firebolt:capability:([a-z0-9-]+)((:[a-z0-9-]+)?)$ |
| `options` | [`GrantModificationOptions`](/docs/150-manage-usergrants#grantmodificationoptions) | false |  |

Promise resolution:

Capabilities:

| Role | Capability |
| --- | --- |
| manages | xrn:firebolt:capability:grants:state |

#### Examples

Default Example

JavaScript:

```
import { UserGrants } from '@firebolt-js/manage-sdk'

let result = await UserGrants.deny(
  'use',
  'xrn:firebolt:capability:localization:postal-code',
  { appId: 'certapp' },
)
console.log(result)
```

Value of `result`:

```
null
```

**JSON-RPC:**

Request:

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "UserGrants.deny",
  "params": {
    "role": "use",
    "capability": "xrn:firebolt:capability:localization:postal-code",
    "options": {
      "appId": "certapp"
    }
  }
}
```

Response:

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
```

---

### device

Get all granted and denied user grants for the device

```
function device(): Promise<GrantInfo[]>
```

Promise resolution:

Capabilities:

| Role | Capability |
| --- | --- |
| uses | xrn:firebolt:capability:grants:state |

#### Examples

Default Example

JavaScript:

```
import { UserGrants } from '@firebolt-js/manage-sdk'

let info = await UserGrants.device()
console.log(info)
```

Value of `info`:

```
;[
  {
    state: 'granted',
    capability: 'xrn:firebolt:capability:localization:postal-code',
    role: 'use',
    lifespan: 'powerActive',
  },
]
```

**JSON-RPC:**

Request:

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "UserGrants.device",
  "params": {}
}
```

Response:

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "state": "granted",
      "capability": "xrn:firebolt:capability:localization:postal-code",
      "role": "use",
      "lifespan": "powerActive"
    }
  ]
}
```

---

### grant

Grants a given capability to a specific app, if appropriate. Calling this results in a persisted active grant that lasts for the duration of the grant policy lifespan.

```
function grant(
  role: Role,
  capability: Capability,
  options: GrantModificationOptions,
): Promise<void>
```

Parameters:

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| `role` | [`Role`](/docs/150-manage-Capabilities-schemas#Role) | true | values: `'use' \| 'manage' \| 'provide'` |
| `capability` | [`Capability`](/docs/150-manage-Capabilities-schemas#Capability) | true | pattern: ^xrn:firebolt:capability:([a-z0-9-]+)((:[a-z0-9-]+)?)$ |
| `options` | [`GrantModificationOptions`](/docs/150-manage-usergrants#grantmodificationoptions) | false |  |

Promise resolution:

Capabilities:

| Role | Capability |
| --- | --- |
| manages | xrn:firebolt:capability:grants:state |

#### Examples

Default Example

JavaScript:

```
import { UserGrants } from '@firebolt-js/manage-sdk'

let result = await UserGrants.grant(
  'use',
  'xrn:firebolt:capability:localization:postal-code',
  { appId: 'certapp' },
)
console.log(result)
```

Value of `result`:

```
null
```

**JSON-RPC:**

Request:

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "UserGrants.grant",
  "params": {
    "role": "use",
    "capability": "xrn:firebolt:capability:localization:postal-code",
    "options": {
      "appId": "certapp"
    }
  }
}
```

Response:

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
```

---

### request

Requests Firebolt to carry out a set of user grants for a given application such that the user grant provider is notified or an existing user grant is reused.

```
function request(
  appId: string,
  permissions: Permission[],
  options: RequestOptions,
): Promise<GrantInfo[]>
```

Parameters:

| Param | Type | Required | Description |
| --- | --- | --- | --- |
| `appId` | `string` | true |  |
| `permissions` | `Permission[]` | true |  |
| `options` | [`RequestOptions`](/docs/150-manage-usergrants#requestoptions) | false | Request options |

Promise resolution:

Capabilities:

| Role | Capability |
| --- | --- |
| manages | xrn:firebolt:capability:grants:state |

#### Examples

Default result #1

JavaScript:

```
import { UserGrants } from '@firebolt-js/manage-sdk'

let info = await UserGrants.request('certapp', [
  {
    role: 'use',
    capability: 'xrn:firebolt:capability:localization:postal-code',
  },
])
console.log(info)
```

Value of `info`:

```
;[
  {
    app: {
      id: 'certapp',
      title: 'Certification App',
    },
    state: 'granted',
    capability: 'xrn:firebolt:capability:localization:postal-code',
    role: 'use',
    lifespan: 'powerActive',
  },
]
```

**JSON-RPC:**

Request:

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "UserGrants.request",
  "params": {
    "appId": "certapp",
    "permissions": [
      {
        "role": "use",
        "capability": "xrn:firebolt:capability:localization:postal-code"
      }
    ]
  }
}
```

Response:

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "app": {
        "id": "certapp",
        "title": "Certification App"
      },
      "state": "granted",
      "capability": "xrn:firebolt:capability:localization:postal-code",
      "role": "use",
      "lifespan": "powerActive"
    }
  ]
}
```

Default result #2

JavaScript:

```
import { UserGrants } from '@firebolt-js/manage-sdk'

let info = await UserGrants.request(
  'certapp',
  [
    {
      role: 'use',
      capability: 'xrn:firebolt:capability:localization:postal-code',
    },
  ],
  {
    force: true,
  },
)
console.log(info)
```

Value of `info`:

```
;[
  {
    app: {
      id: 'certapp',
      title: 'Certification App',
    },
    state: 'granted',
    capability: 'xrn:firebolt:capability:localization:postal-code',
    role: 'use',
    lifespan: 'powerActive',
  },
]
```

**JSON-RPC:**

Request:

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "UserGrants.request",
  "params": {
    "appId": "certapp",
    "permissions": [
      {
        "role": "use",
        "capability": "xrn:firebolt:capability:localization:postal-code"
      }
    ],
    "options": {
      "force": true
    }
  }
}
```

Response:

```
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "app": {
        "id": "certapp",
        "title": "Certification App"
      },
      "state": "granted",
      "capability": "xrn:firebolt:capability:localization:postal-code",
      "role": "use",
      "lifespan": "powerActive"
    }
  ]
}
```

---

## Types

### GrantState

The state the grant is in

```
GrantState: {
    GRANTED: 'granted',
    DENIED: 'denied',
},
```

---

### GrantModificationOptions

Options when modifying any grant

```
type GrantModificationOptions = {
  appId?: string
}
```

---

### RequestOptions

```
type RequestOptions = {
  force?: boolean // Whether to force for user grant even if the previous decision stored
}
```

---

### AppInfo

Information about an app that a grant was for

```
type AppInfo = {
  id: string
  title?: string
}
```

---

### GrantInfo

Information about a grant given by a user

```
type GrantInfo = {
  app?: AppInfo // Information about an app that a grant was for
  state: GrantState // The state the grant is in
  capability: Capability // A Capability is a discrete unit of functionality that a Firebolt device might be able to perform.
  role: Role // Role provides access level for the app for a given capability.
  lifespan: 'once' | 'forever' | 'appActive' | 'powerActive' | 'seconds'
  expires?: string
}
```

See also:

[AppInfo](/docs/150-manage-usergrants#appinfo) [GrantState](/docs/150-manage-usergrants#grantstate) [Capability](/docs/150-manage-Capabilities-schemas#Capability) [Role](/docs/150-manage-Capabilities-schemas#Role)

---