UserGrants Module

Version UserGrants 1.0.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<object[]>

Parameters:

Param Type Required Description
appId string true  

Promise resolution:

object[]

Capabilities:

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

Examples

Default Example

JavaScript:

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

UserGrants.app("certapp")
    .then(info => {
        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<object[]>

Parameters:

Param Type Required Description
capability Capability true
pattern: ^xrn:firebolt:capability:([a-z0-9-]+)((:[a-z0-9-]+)?)$

Promise resolution:

object[]

Capabilities:

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

Examples

Default Example

JavaScript:

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

UserGrants.capability("xrn:firebolt:capability:localization:postal-code")
    .then(info => {
        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?: object): 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 object false  

Promise resolution:

void

Capabilities:

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

Examples

Default Example

JavaScript:

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

UserGrants.clear("use", "xrn:firebolt:capability:localization:postal-code", {"appId":"certapp"})
    .then(result => {
        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?: object): 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 object false  

Promise resolution:

void

Capabilities:

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

Examples

Default Example

JavaScript:

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

UserGrants.deny("use", "xrn:firebolt:capability:localization:postal-code", {"appId":"certapp"})
    .then(result => {
        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<object[]>

Promise resolution:

object[]

Capabilities:

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

Examples

Default Example

JavaScript:

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

UserGrants.device()
    .then(info => {
        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?: object): 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 object false  

Promise resolution:

void

Capabilities:

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

Examples

Default Example

JavaScript:

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

UserGrants.grant("use", "xrn:firebolt:capability:localization:postal-code", {"appId":"certapp"})
    .then(result => {
        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<object[]>

Parameters:

Param Type Required Description  
appId string true    
, permissions Permission[] true  
, options RequestOptions false Request options

Promise resolution:

object[]

Capabilities:

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

Examples

Default result #1

JavaScript:

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

UserGrants.request("certapp",
                   [
                     {
                       "role": "use",
                       "capability": "xrn:firebolt:capability:localization:postal-code"
                     }
                   ],
                   null)
    .then(info => {
        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'

UserGrants.request("certapp",
                   [
                     {
                       "role": "use",
                       "capability": "xrn:firebolt:capability:localization:postal-code"
                     }
                   ],
                   {
                     "force": true
                   })
    .then(info => {
        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

AppInfo

Information about an app that a grant was for

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

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
}

GrantState

The state the grant is in

enum GrantState {
	GRANTED = 'granted',
	DENIED = 'denied'
}

GrantInfo

Information about a grant given by a user

type GrantInfo = {
  app?: {
    id: string
    title?: string
  }
  state: 'granted' | 'denied'                                             // 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:

string ‘use’ | ‘manage’ | ‘provide’