Retrieving Entitlements

Entitlements APIs for retrieving user entitlements information

getEntitlementsConsumption

The user's current entitlement status can be retrieved by calling the getEntitlementsConsumption method. This retrieves information about the user's current level of entitlement as well as information about any entitlements consumed.

Swift

do {
  let entitlements = try await entitlementsClient.getEntitlementsConsumption()
  // Handle entitlements
} catch {
  // Handle error
}

Kotlin

try {
  val consumption = entitlementsClient.getEntitlementsConsumption()
  // Handle consumption
}
catch (e: SudoEntitlements.EntitlementsException) {
  // Handle error
}

JavaScript

try {
  const consumption = await entitlementsClient.getEntitlementsConsumption()
  // Handle consumption
}
catch (err) {
  // Handle error
}

The getEntitlementsConsumption method returns an EntitlementsConsumption object that specifies both the user's entitlements and any consumption of those entitlements.

Entitlements may be consumed by the user themselves or may be consumed by sub-resources of the user.

For example the sudoplatform.sudo.max entitlement controls the maximum number of Sudo Profiles a user may have at any one time. This entitlement is consumed at the user level. Conversely the sudoplatform.virtual-cards.virtual-cardMaxPerSudo specifies how many Sudo Virtual Cards may be active for any single Sudo Profile. Each Sudo Profile's consumption of this entitlement is listed separately in the EntitlementsConsumption object. Consumers are identified by an id (in the case of a Sudo Profile this is the Sudo Profile's ID) and the issuer of the ID (sudoplatform.sudoservice for Sudo Profile IDs).

Errors

The getEntitlementsConsumption API will throw errors in the the following circumstances:

Swift

Exception	Condition	Action
.notSignedIn	User was not signed in when getEntitlements was invoked.	Ensure user is signed in prior to invoking getEntitlements
.invalidToken	The user's token does not contain a claim that can be mapped to an entitlements set, or the user has not been pre-configured with initial entitlements.	Ensure your identity provider has been set up to include an expected claim when federating sign-on or pre-configure the user with entitlements.
.noEntitlementsError	The user has not called redeemEntitlements yet and so their identity is not bound to any entitlements	Ensure redeemEntitlements has been called prior to attempting to retrieve entitlements consumption information
.serviceError	A transient error occurred in the service while retrieving entitlements.	Retry the request. If the problem persists, ask us for help

Kotlin

Errors in Kotlin are thrown as exceptions in the SudoEntitlementsClient.EntitlementsException class name space.

Exception	Condition	Action
NotSignedInException	User was not signed in when getEntitlementsConsumption was invoked.	Ensure user is signed in prior to invoking getEntitlementConsumption
InvalidTokenException	The user's token does not contain a claim that can be mapped to an entitlements set, or has the user been pre-configured with initial entitlements.	Ensure your identity provider has been set up to include an expected claim when federating sign-on or pre-configure the user with entitlements.
NoEntitlementsException	The user has not called redeemEntitlements yet and so their identity is not bound to any entitlements	Ensure redeemEntitlements has been called prior to attempting to retrieve entitlements consumption information
UnknownException	A transient error occurred in the service while retrieving entitlements.	Retry the request. If the problem persists, ask us for help

JavaScript

Error	Condition	Action
NotSignedInError	User was not signed in when getEntitlements was invoked.	Ensure user is signed in prior to invoking getEntitlements
InvalidTokenError	The user's token does not contain a claim that can be mapped to an entitlements set, or has the user been pre-configured with initial entitlements.	Ensure your identity provider has been set up to include an expected claim when federating sign-on or pre-configure the user with entitlements.
NoEntitlementsError	The user has not called redeemEntitlements yet and so their identity is not bound to any entitlements	Ensure redeemEntitlements has been called prior to attempting to retrieve entitlements consumption information
ServiceError	A transient error occurred in the service while retrieving entitlements.	Retry the request. If the problem persists, ask us for help