LogoLogo
  • Platform Overview
  • 🗺️Guides
    • Getting Started
    • Users
      • Integrate the User SDK
      • Registration
      • Authentication
      • SDK Releases
      • API Reference
    • Entitlements
      • Administrative API
        • Integrating the Administrative API
        • Entitlement Definitions
        • Managing Entitlements Sets
        • Managing Entitlements Sequences
        • Managing User Entitlements
        • API Schema
      • End-user API
        • Integrate the Entitlements SDK
        • Redeeming Entitlements
        • Retrieving Entitlements
        • SDK Releases
        • API Reference
    • Sudos
      • Integrate the Sudo Profiles SDK
      • Sudo Entitlements
      • Manage Sudos
      • SDK Releases
      • API Reference
    • Telephony
      • Integrate the Telephony SDK
      • Manage Phone Numbers
      • Text Messaging
      • Voice Calling
      • Telephony Simulator
      • SDK Releases
      • API Reference
    • Email
      • Integrate the Email SDK
      • Email Entitlements
      • Manage Email Addresses
      • Sending & Receiving Email
      • Manage Email Folders
      • Draft Email Messages
      • Schedule Send
      • Manage Email Address Blocklists
      • Email Address Public Information
      • Pagination
      • Caching
      • Configuration Data
      • Email Notifications
      • SDK Releases
      • API Reference
    • Decentralized Identity
      • Edge Agent
        • Relay SDK
          • Integrate the Relay SDK
          • Relay Entitlements
          • Manage Relay Postboxes
          • Manage Relay Messages
          • Receiving Messages
          • SDK Releases
        • Edge Agent SDK
          • Integrate the Edge Agent SDK
          • Agent Management
          • Manage Wallets
          • Establishing Connections
          • Manage Connections
          • Messaging
          • Manage DIDs
          • Accepting New Credentials
          • Manage Credentials
          • Present Credentials for Verification
          • Utilize Alternative Cryptography Providers
          • SDK Releases
          • Standards and Protocols
      • Cloud Agent
        • Cloud Agent Admin API
          • Integrate the Cloud Agent Admin API
          • Aries Interop Profile (AIP)
            • Connection Exchanges
            • Credential Exchanges
            • Proof Exchanges
          • Connections
          • Basic Messages
          • Credentials
            • Anoncreds Credentials
              • Schemas
              • Credential Definitions
            • W3C Credentials
          • Audit Logs
          • API Schema
          • Error Codes
          • Standards and Protocols
    • Virtual Cards
      • Integrate the Virtual Cards SDK
      • Virtual Cards Entitlements
      • Virtual Cards Transaction Velocity Constraints
      • Key Management
      • Manage Funding Sources
      • Manage Virtual Cards
      • Manage Transactions
      • Configuration Data
      • Pagination
      • Caching
      • SDK Releases
      • API Reference
    • Virtual Cards Simulator
      • Integrate the Virtual Cards Simulator SDK
      • Simulate Authorizations
      • Simulate Debits
      • Simulate Refunds
      • Simulate Reversals
      • Merchants and Currencies
      • SDK Releases
      • API Reference
    • Virtual Private Network
      • Integrate the VPN SDK
      • VPN Entitlements
      • Manage Servers
      • Manage Connection
      • Observe VPN Related Events
      • SDK Releases
      • API Reference
      • Frequently Asked Questions
    • Secure ID Verification
      • Integrate the Secure ID Verification SDK
      • List Supported Countries
      • Verify an Identity
      • Check Secure ID Verification Status
      • Use the Secure ID Verification Simulator
      • SDK Releases
      • API Reference
    • Password Manager
      • Integrate the Password Manager SDK
      • Accessing the Password Manager
      • Managing Password Vaults
      • Managing Password Vault Items
      • Vault Import and Export
      • Password Utilities
      • Password Manager Entitlements
      • Password Vault Security
      • SDK Releases
      • API Reference
    • Ad/Tracker Blocker
      • Integrate the Ad/Tracker Blocker SDK
      • Manage Rulesets
      • Blocking Ads and Trackers
      • Manage Exceptions
      • SDK Releases
      • API Reference
    • Site Reputation
      • Integrate the Site Reputation SDK
      • Use the Site Reputation SDK
      • SDK Releases
      • API Reference
  • 💡Concepts
    • Sudo Digital Identities
  • 🧱Development
    • Versioning
  • 🏢Administration
    • Admin Console Roles
  • ❓Get Help
    • Request a Demo
    • Report an Issue
Powered by GitBook
On this page
  1. Guides
  2. Entitlements
  3. Administrative API

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

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

PreviousManaging User EntitlementsNextEnd-user API

Last updated 7 months ago

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

🗺️
GraphQL specification