Requesting Capabilities

Requesting capabilities from another app

Capabilities

Capabilities is an API that allows apps to request authorization from another app.

capabilities: {
  collect: () => Promise<Maybe<string>> // returns username
  request: (options?: CapabilitiesImpl.RequestOptions) => Promise<void>
  session: (username: string) => Promise<Maybe<Session>>
}

Capabilities includes:

• collect. Collects UCANs and file system secrets.

• request. Requests authorization from another app.

• session. Creates a session after authorization has been granted.

We saw earlier in Authentication Strategies how an app can register a user and link their account across devices. Authentication strategies are designed for use within a single web app across multiple devices.

Capabilities are an API for linking between apps. One app requests permission to access some set of resources from a second app with capability equal to or greater than the requested permissions. On user approval, the second app returns capability to the first app in the form of UCANs and file system secrets.

Fission Auth Lobby only. At present, the only app that can provide capabilities to another app is the Fission Auth Lobby. We plan to open capabilities provisioning to other apps in a future release.

Requesting capabilities

Here is an example of requesting capabilities from the Fission Auth Lobby:

// We define a `Permissions` object,
// which represents which permissions to request from the user
const permissions = {
  // A permission that requests read and write access to
  // private/Apps/Nullsoft/Winamp
  app: { creator: "Nullsoft", name: "Winamp" }
}

// Permissions are passed to ODD SDK at initialization
const program = await odd.program({
  namespace: { creator: "Nullsoft", name: "Winamp" },
  permissions
})

// (a) Whenever you are ready to redirect to the lobby to request capabilities 
// call the request function:
program.capabilities.request()

// (b) When you have been redirected back from the lobby and
// your program re-initializes, you will have access to the user session.
session = program.session

When the ODD SDK redirects a user to the Fission Auth Lobby, they will see a prompt with the permissions that your app has requested. The user can choose to accept or decline the request.

Either way, the Fission Auth Lobby redirects the user to your app. If the user accepted, the ODD SDK will automatically create a session at program initialization.