- Print
UserGrants
- Print
UserGrants Module 0.15.0
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[]): Promise<object[]>
Parameters:
Param | Type | Required | Description |
---|---|---|---|
appId | string | true | |
permissions | Permission[] | true |
Promise resolution:
object[]
Capabilities:
Role | Capability |
---|---|
manages | xrn:firebolt:capability:grants:state |
Examples
Default result
JavaScript:
import { UserGrants } from '@firebolt-js/manage-sdk'
UserGrants.request("certapp",
[
{
"role": "use",
"capability": "xrn:firebolt:capability:localization:postal-code"
}
])
.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"
}
]
}
Types
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'
GrantModificationOptions
Options when modifying any grant
type GrantModificationOptions = {
appId?: string
}
AppInfo
Information about an app that a grant was for
type AppInfo = {
id: string
title?: string
}
GrantState
The state the grant is in
enum GrantState {
GRANTED = 'granted',
DENIED = 'denied'
}