1.2.0-manage-UserGrants

UserGrants

Article summary

Did you find this summary helpful?

Thank you for your feedback

title: UserGrants

version: 1.2.0
layout: default
sdk: manage

# UserGrants Module

Version UserGrants 1.2.0

Table of Contents
Usage
Overview
Methods
Types

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`	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`	true	values: `'use' \\| 'manage' \\| 'provide'`
`capability`	`Capability`	true	pattern: ^xrn:firebolt:capability:([a-z0-9-]+)((:[a-z0-9-]+)?)$
`options`	`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`	true	values: `'use' \\| 'manage' \\| 'provide'`
`capability`	`Capability`	true	pattern: ^xrn:firebolt:capability:([a-z0-9-]+)((:[a-z0-9-]+)?)$
`options`	`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`	true	values: `'use' \\| 'manage' \\| 'provide'`
`capability`	`Capability`	true	pattern: ^xrn:firebolt:capability:([a-z0-9-]+)((:[a-z0-9-]+)?)$
`options`	`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`	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',
    },
  ],
  null,
)
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
}

What's Next

VoiceGuidance

Table of contents

version: 1.2.0 layout: default sdk: manage
Table of Contents
Usage
Overview
Methods
Types

UserGrants

version: 1.2.0 layout: default sdk: manage

Table of Contents

Usage

Overview

Methods

app

Examples

capability

Examples

clear

Examples

deny

Examples

device

Examples

grant

Examples

request

Examples

Types

GrantState

GrantModificationOptions

RequestOptions

AppInfo

GrantInfo

What's Next

version: 1.2.0
layout: default
sdk: manage