UserGrants Module

Version UserGrants 1.2.0

Table of Contents

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
}

See also:

AppInfo GrantState Capability Role