# 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

```graphql
# 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.

```graphql
# 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.

{% tabs %}
{% tab title="Swift" %}

```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.
}
```

{% endtab %}

{% tab title="Kotlin" %}

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

{% endtab %}

{% tab title="TypeScript" %}

```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)

```

{% endtab %}
{% endtabs %}

## Get an Entitlements Set

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

```graphql
# 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.

{% tabs %}
{% tab title="Swift" %}

```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.
}
```

{% endtab %}

{% tab title="Kotlin" %}

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

{% endtab %}

{% tab title="TypeScript" %}

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

```

{% endtab %}
{% endtabs %}

## 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
```

```graphql
# 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.

{% tabs %}
{% tab title="Swift" %}

```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.
}
```

{% endtab %}

{% tab title="Kotlin" %}

```kotlin
val listOutput =
    client.listEntitlementsSets(
        null 
    )
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const listOutput = await client.listEntitlementsSets()

```

{% endtab %}
{% endtabs %}

## Update an Existing Entitlements Set

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

```graphql
# 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.

{% tabs %}
{% tab title="Swift" %}

```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.
}    

```

{% endtab %}

{% tab title="Kotlin" %}

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

{% endtab %}

{% tab title="TypeScript" %}

```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)

```

{% endtab %}
{% endtabs %}

## 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.

```graphql
# 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.

{% tabs %}
{% tab title="Swift" %}

```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.
} 
```

{% endtab %}

{% tab title="Kotlin" %}

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

{% endtab %}

{% tab title="TypeScript" %}

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

```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sudoplatform.com/guides/entitlements/administrative-api/managing-entitlements-sets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.