Managing Entitlements Sets

Administrative APIs for managing entitlements sets

The standard create, read, update and delete management operations are performed by calling the addEntitlementsSet, getEntitlementsSet or listEntitlementsSets, setEntitlementsSet, and removeEntitlementsSet APIs respectively.

Common Entitlements Sets Types

# An entitlement
type Entitlement {
  # Name of the entitlement
  name: String!

  # Optional description of the entitlement
  description: String

  # Value of the entitlement. Type Float to allow for values
  # values larger than possible with Int. Value is a
  # positive integer.
  value: Float!
}

# A set of entitlements
type EntitlementsSet {
  # Time of initial creation of an entitlements set in milliseconds
  # since epoch. Number is integral, float type provides sufficient
  # precision.
  createdAtEpochMs: Float!

  # Time of most recent update of an entitlements set in milliseconds
  # since epoch. Number is integral, float type provides sufficient
  # precision.
  updatedAtEpochMs: Float!

  # Version of the entitlements set. Incremented each time an update is made.
  version: Int!

  # Name of the entitlements set.
  name: String!

  # Optional description of the entitlements set.
  description: String

  # Entitlements conferred by this entitlements set.
  entitlements: [Entitlement!]!
}

Add a New Entitlements Set

A new entitlements set can be added to the system by calling the addEntitlementsSet mutation.

# Input for the addEntitlementsSet mutation
input AddEntitlementsSetInput {
  name: String!
  description: String
  entitlements: [EntitlementInput!]!
}

type Mutation {
  # Adds an entitlement set
  addEntitlementsSet(
    input: AddEntitlementsSetInput!
  ): EntitlementsSet!
}

Possible Errors

• InvalidEntitlementsError will be returned if an entitlement name is not a recognized entitlement.

• ServiceError will be returned for internal errors.

Adding a new entitlements set using SDK.

Swift

do {
    let entitlementsSet = try await client.addEntitlementsSetWithName(
        name: "Premium user",
        description: "Entitlements set for premium users",
        entitlements: [Entitlement(name: "sudoplatform.sudo.max", description: "Max. Sudos", value: 3)]
    )
} catch {    
    // Handle error. An error may be thrown if the backend is unable perform
    // the operation due to invalid input, availability or security issues.
}

Kotlin

val entitlementsSet =
    client.addEntitlementsSet(
        "Premium user", 
        "Entitlements set for premium users",
        listOf(
            Entitlement("sudoplatform.sudo.max", "Max. Sudos", 3)
        )
    )

TypeScript

const input = {
  name: 'Premium user',
  description: 'Entitlements for premium users',
  entitlements: [
    {
      name: 'sudoplatform.sudo.max',
      description: 'Max. Sudos',
      value: 3,
    }
  ],
}
const entitlementsSet = await client.addEntitlementsSet(input)

Get an Entitlements Set

Call the getEntitlementsSet query to retrieve an entitlements set by name.

# Input for the getEntitlementsSet query
input GetEntitlementsSetInput {
  name: String!
}

type Query {
  # Gets an entitlement set.
  getEntitlementsSet(
    input: GetEntitlementsSetInput!
  ): EntitlementsSet
}

Possible Errors

• ServiceError will be returned for internal errors.

Retrieving an entitlements set using SDK.

Swift

do {
    let entitlementsSet = try await client.getEntitlementsSetWithName(
        name: "Premium user",
    ) 
} catch let error {
    // Handle error. An error may be thrown if the backend is unable perform
    // the operation due to invalid input, availability or security issues.
}

Kotlin

val entitlementsSet =
    client.getEntitlementsSet(
        "Premium user"
    )

TypeScript

const input = {
  name: 'Premium user',
}
const entitlementsSet = await client.getEntitlementsSet(input)

List all Entitlements Sets

Call the listEntitlementsSet query to list all of the entitlements sets in the system. The results list is paginated with a page size of 10. To retrieve all results your application must implement the following algorithm.

1. Call listEntitlementsSet query with nextToken set to null
2. If nextToken in the returned EntitlementsSetsConnection is null, 
   there are no more results to retrieve
3. Call listEntitlementsSet query with nextToken set to the value
   returned from the previous call
4. Go to step 2

# Pagination connection for use when listing entitlements sets
type EntitlementsSetsConnection {
  items: [EntitlementsSet!]!
  nextToken: String
}

# Input for the listEntitlementsSets query
input ListEntitlementsSetsInput {
  token: String!
}

type Query {
# Retrieves all entitlements sets.
listEntitlementsSets(
  nextToken: String
): EntitlementsSetsConnection!
}

Possible Errors

• ServiceError will be returned for internal errors.

Listing entitlements sets using SDK.

Swift

do {
    let listOutput = try await client.listEntitlementsSetsWithNextToken(
        nextToken: nil
    ) 
} catch {
    // Handle error. An error may be thrown if the backend is unable perform
    // the operation due to invalid input, availability or security issues.
}

Kotlin

val listOutput =
    client.listEntitlementsSets(
        null 
    )

TypeScript

const listOutput = await client.listEntitlementsSets()

Update an Existing Entitlements Set

Call the setEntitlementsSet mutation to update the contents of an existing entitlements set. The updated entitlements set is returned.

# Input representing an entitlement
input EntitlementInput {
  name: String!
  description: String
  value: Int!
}

# Input for the setEntitlementsSet mutation
input SetEntitlementsSetInput {
  name: String!
  description: String
  entitlements: [EntitlementInput!]!
}

type Mutation {
  # Change the entitlements conferred by an entitlements set.
  setEntitlementsSet(input: SetEntitlementsSetInput!): EntitlementsSet!
}

Possible Errors

• InvalidEntitlementsError will be returned if an entitlement name is not a recognized entitlement.

• ServiceError will be returned for internal errors.

Updating an entitlements set using SDK.

Swift

do {
    let entitlementsSet = try await client.setEntitlementsSetWithName(
        name: "Premium user",
        description: "Entitlements set for premium users",
        entitlements: [Entitlement(name: "sudoplatform.sudo.max", description: "Max. Sudos", value: 5)]
    ) 
} catch {
    // Handle error. An error may be thrown if the backend is unable perform
    // the operation due to invalid input, availability or security issues.
}    

Kotlin

val entitlementsSet =
    client.setEntitlementsSet(
        "Premium user", 
        "Entitlements set for premium users",
        listOf(
            Entitlement("sudoplatform.sudo.max", "Max. Sudos", 5)
        )
    )

TypeScript

const input = {
  name: 'Premium user',
  description: 'Entitlements for premium users',
  entitlements: [
    {
      name: 'sudoplatform.sudo.max',
      description: 'Max. Sudos',
      value: 3,
    }
  ],
}
const entitlementsSet = await client.setEntitlementsSet(input)

Remove an Entitlements Set

Call the removeEntitlementsSet mutation to remove an existing entitlements set by name. The removed entitlements set is returned on success. null is returned if the named entitlements set cannot be found.

# Input for the removeEntitlementsSet mutation
input RemoveEntitlementsSetInput {
  name: String!
}

type Mutation {
  # Remove an entitlements set. Any users configured against this
  # entitlements set will become unentitled.
  removeEntitlementsSet(input: RemoveEntitlementsSetInput!): EntitlementsSet
}

Possible Errors

• EntitlementsSetInUseError will be returned if any entitlements sequences exist that reference the entitlements set

• ServiceError will be returned for internal errors.

Removing an entitlements set using SDK.

Swift

do {
    let entitlementsSet = try await client.removeEntitlementsSetWithName(
        name: "Premium user"
    )
} catch {
    // Handle error. An error may be thrown if the backend is unable perform
    // the operation due to invalid input, availability or security issues.
} 

Kotlin

val entitlementsSet =
    client.removeEntitlementsSet(
        "Premium user"
    )

TypeScript

const input = {
  name: 'Premium user',
}
const entitlementsSet = await client.removeEntitlementsSet(input)