API Schema

The GraphQL API schema for the Sudo Platform Entitlements administrative API

# 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!
}

# Entitlement Type in an entitlement definition: "numeric" or "boolean"
scalar EntitlementType

# 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!]!
}

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

# Definition of an Entitlement
type EntitlementDefinition {
  name: String!
  description: String
  type: EntitlementType!
  expendable: Boolean!
}

# Pagination connection for use when listing entitlement definitions
type EntitlementDefinitionConnection {
  items: [EntitlementDefinition!]!
  nextToken: String
}

# Definition of a single transition within an entitlements sequence
type EntitlementsSequenceTransition {
  # Name of entitlements set
  entitlementsSetName: String!

  # ISO8601 period string - if not specified then this transition
  # is the final state for all users on the sequence.
  duration: String
}

# Definition of a sequence of entitlements sets through which a user will transition
type EntitlementsSequence {
  # Name of the entitlements sequence
  name: String!

  # Description of the entitlements sequence
  description: String

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

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

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

  # Sequence of transitions a user will go through in order. Must not be empty.
  transitions: [EntitlementsSequenceTransition!]!
}

# Pagination connection for use when listing entitlements sequences
type EntitlementsSequencesConnection {
  items: [EntitlementsSequence!]!
  nextToken: String
}

# Effective entitlements for an external user
type ExternalUserEntitlements {
  # Time of initial creation of user entitlements mapping in milliseconds
  # since epoch. Number is integral, float type provides sufficient
  # precision.
  createdAtEpochMs: Float!

  # Time of last updates of user entitlements mapping in milliseconds
  # since epoch. Number is integral, float type provides sufficient
  # precision.
  updatedAtEpochMs: Float!

  # Version number of the user's entitlements. This is incremented every
  # time there is a change of entitlements set or explicit entitlements
  # for this user.
  #
  # For users entitled by entitlement set, the fractional part of this version
  # specifies the version of the entitlements set itself. Entitlements set version
  # is divided by 100000 then added to the user entitlements version
  #
  # This ensures that the version of user entitlements always increases mon
  version: Float!

  # External IDP identifier identifying the user
  externalId: String!

  # Sudo Platform owner. This value matches the subject in identity
  # tokens used to authenticate to Sudo Platform services.
  owner: String

  # Name of the entitlements set specified for this user. Will be undefined
  # if entitlements have been specified explicitly rather than by an
  # entitlements set name.
  entitlementsSetName: String

  # Name of the entitlements sequence specified for this user. Will be undefined
  # if entitlements have been specified explicitly or by entitlements set
  # rather than by an entitlements sequence name.
  entitlementsSequenceName: String

  # Effective entitlements for the user either obtained from the entitlements
  # set or as specified explicitly for this user.
  entitlements: [Entitlement!]!

  # Expendable entitlements for the user.
  expendableEntitlements: [Entitlement!]!

  # Milliseconds since epoch from when user's transitions should
  # be calculated. Defaults to current time.
  # Is a Float only for precision. Must be an integral value.
  transitionsRelativeToEpochMs: Float
}

# An error result returned for an operation in a bulk applyEntitlements*ToUsers
# mutation.
type ExternalUserEntitlementsError {
  # Error code of failed operation
  error: String!
}

# Union of success and error results returned for operations in a bulk
# applyEntitlements*ToUsers mutation.
union ExternalUserEntitlementsResult =
    ExternalUserEntitlements
  | ExternalUserEntitlementsError

# An aggregated list of entitlement consumption information for an external user.
type ExternalEntitlementsConsumption {
  # User's active entitlements
  entitlements: ExternalUserEntitlements!
  # User's entitlement consumption
  consumption: [EntitlementConsumption!]!
}

# Entitled user.
type EntitledUser {
  externalId: String!
}

# Input representing an entitlement
input EntitlementInput {
  # Name of the entitlement
  name: String!

  # Description, if any, of the entitlement as specified by the entitlements
  #  administrator.
  description: String

  # Value of the entitlement. Type Float to allow for values
  # values larger than possible with Int. Value is a
  # positive integer. Maximum value on input is 2^52-1
  value: Float!
}

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

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

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

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

# Input for the applyEntitlementsSetToUser mutation
input ApplyEntitlementsSetToUserInput {
  externalId: String!
  entitlementsSetName: String!
}

# Input for the applyEntitlementsSetToUsers mutation
input ApplyEntitlementsSetToUsersInput {
  operations: [ApplyEntitlementsSetToUserInput!]!
}

# Input for the applyEntitlementsSequenceToUser mutation
input ApplyEntitlementsSequenceToUserInput {
  externalId: String!
  entitlementsSequenceName: String!

  # Milliseconds since epoch from when user's transitions should
  # be calculated. Defaults to current time.
  # Is a Float only for precision. Must be an integral value.
  transitionsRelativeToEpochMs: Float
}

# Input for the applyEntitlementsSequenceToUsers mutation
input ApplyEntitlementsSequenceToUsersInput {
  operations: [ApplyEntitlementsSequenceToUserInput!]!
}

# Input for the applyEntitlementsToUser mutation
input ApplyEntitlementsToUserInput {
  externalId: String!
  entitlements: [EntitlementInput!]!
}

# Input for the applyEntitlementsToUsers mutation
input ApplyEntitlementsToUsersInput {
  operations: [ApplyEntitlementsToUserInput!]!
}

# Input for the applyExpendableEntitlementsToUser mutation
input ApplyExpendableEntitlementsToUserInput {
  externalId: String!
  expendableEntitlements: [EntitlementInput!]!
  requestId: ID!
}

# Input for the getEntitlementsForUser query
input GetEntitlementsForUserInput {
  externalId: String!
}

# Input for the getEntitlementDefinition query
input GetEntitlementDefinitionInput {
  name: String!
}

# Input of a single transition within an entitlements sequence
input EntitlementsSequenceTransitionInput {
  # Name of entitlements set
  entitlementsSetName: String!

  # ISO8601 period string - if not specified then this transition
  # is the final state for all users on the sequence.
  duration: String
}

# Input for the getEntitlementsSequence query
input GetEntitlementsSequenceInput {
  name: String!
}

# Input for the addEntitlementsSequence mutation
input AddEntitlementsSequenceInput {
  # Name of the entitlements sequence
  name: String!

  # Description of the entitlements sequence
  description: String

  # Sequence of transitions a user will go through in order. Must not be empty.
  transitions: [EntitlementsSequenceTransitionInput!]!
}

# Input for the setEntitlementsSequence mutation
input SetEntitlementsSequenceInput {
  # Name of the entitlements sequence
  name: String!

  # Description of the entitlements sequence
  description: String

  # Sequence of transitions a user will go through in order. Must not be empty.
  transitions: [EntitlementsSequenceTransitionInput!]!
}

# Input for the removeEntitlementsSequence mutation
input RemoveEntitlementsSequenceInput {
  name: String!
}

# Input for the removeEntitledUser mutation
input RemoveEntitledUserInput {
  externalId: String!
}

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

  # Retrieves all entitlements sets.
  listEntitlementsSets(nextToken: String): EntitlementsSetsConnection!

  # Gets an entitlement sequence.
  getEntitlementsSequence(
    input: GetEntitlementsSequenceInput!
  ): EntitlementsSequence

  # Retrieves all entitlements sequences.
  listEntitlementsSequences(
    nextToken: String
  ): EntitlementsSequencesConnection!

  # Gets an entitlement definition
  getEntitlementDefinition(
    input: GetEntitlementDefinitionInput!
  ): EntitlementDefinition

  # Retrieves all entitlements definitions
  listEntitlementDefinitions(
    limit: Int
    nextToken: String
  ): EntitlementDefinitionConnection!

  # Retrieve effective entitlements for a given external user.
  getEntitlementsForUser(
    input: GetEntitlementsForUserInput!
  ): ExternalEntitlementsConsumption!
}

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

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

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

  # Adds an entitlement sequence
  addEntitlementsSequence(
    input: AddEntitlementsSequenceInput!
  ): EntitlementsSequence!

  # Replace the definition of an entitlements sequence
  setEntitlementsSequence(
    input: SetEntitlementsSequenceInput!
  ): EntitlementsSequence!

  # Remove an entitlements sequence. Any users configured against this entitlements
  # sequence will become unentitled.
  removeEntitlementsSequence(
    input: RemoveEntitlementsSequenceInput!
  ): EntitlementsSequence

  # Apply an entitlement set with the specified name to a user.
  applyEntitlementsSetToUser(
    input: ApplyEntitlementsSetToUserInput!
  ): ExternalUserEntitlements!

  # Apply an entitlement set with the specified names to users in bulk.
  # Equivalent to calling applyEntitlementsSetToUser
  # for each operation.
  applyEntitlementsSetToUsers(
    input: ApplyEntitlementsSetToUsersInput!
  ): [ExternalUserEntitlementsResult!]!

  # Apply an entitlement sequence with the specified name to a user.
  applyEntitlementsSequenceToUser(
    input: ApplyEntitlementsSequenceToUserInput!
  ): ExternalUserEntitlements!

  # Apply an entitlement sequence with the specified names to users in bulk.
  # Equivalent to calling applyEntitlementsSequenceToUser
  # for each operation.
  applyEntitlementsSequenceToUsers(
    input: ApplyEntitlementsSequenceToUsersInput!
  ): [ExternalUserEntitlementsResult!]!

  # Apply entitlements to a user without using a named entitlements set.
  applyEntitlementsToUser(
    input: ApplyEntitlementsToUserInput!
  ): ExternalUserEntitlements!

  # Apply entitlements to users without using a named entitlements set.
  # Equivalent to calling applyEntitlementsToUser
  # for each operation.
  applyEntitlementsToUsers(
    input: ApplyEntitlementsToUsersInput!
  ): [ExternalUserEntitlementsResult!]!

  # Apply expendable entitlements to a user
  applyExpendableEntitlementsToUser(
    input: ApplyExpendableEntitlementsToUserInput!
  ): ExternalUserEntitlements!

  # Remove an entitled user. Entitlements and consumption records related
  # to the specified user will be removed.
  removeEntitledUser(input: RemoveEntitledUserInput!): EntitledUser
}

Errors

In general, errors specific to each API defined in the schema will be returned in the HTTP body as GraphQL error (please see GraphQL specification for more detail). However, some system wide errors maybe returned via HTTP status:

• 401: This indicates that you are using the wrong API key to access the Graph API.

• 403: This indicates that the access was denied due to a security policy.

• 423: This indicates the system is currently unavailable due to maintenance.

• 500: This indicates that there's an internal service error. This maybe transient but it unlikely to be resolved in a short amount of time.

• 503: This indicates the service is temporarily unavailable but it is likely to be restored shortly.