GraphQL

GraphQL is a graph based JSON API over HTTP. It exposes a strongly typed schema with query and mutation operations. In User Management, the graph is based on the account, with sub-elements such as linked accounts and devices that belong to that particular account. Moreover, the User Management GraphQL API allows to manage buckets linked to user accounts.

Queries and Mutations

The operations are categorized into two types: query and mutation.

Queries

The possible queries for accounts are:

Listing 188 GraphQL Queries
accountByUserName(userName: String!) : Account

accountById(accountId: String!) : Account

accountByEmail(email: String!) : Account

accountByPhoneNumber(phoneNumber: String!) : Account

accounts(
    activeAccountsOnly: Boolean = true
    first: Int
    after: String
    sorting: Sorting = {sortOrder: DESCENDING}
    filtering : Filtering
) : AccountConnection!

credentialPolicy: CredentialPolicyDescriptor

If a Credential Manager is configured with a credential policy, the following queries are also available:

Listing 189 GraphQL Credential Policy Rules Queries
credentialPolicyRulesStateByUserName(userName: String!) : CredentialPolicyRulesState

If a bucket datasource is configured in the User Management profile, the following queries are also available:

Listing 190 GraphQL Queries
bucketsByUserName(
    userName: String!
    purposes: [String!]!
) : [Bucket!]!

As can be determined from the names, they operate on singular or plural accounts.

The account type provides information about the account (attributes of an account) as well as devices and dynamic clients associated with that account. The inclusion of dynamic clients is disabled by default and can be enabled by setting include-dynamic-clients-in-graph-QL-account-response to true under /profiles/profile (user-management-service)/settings/user-management-service/include-dynamic-clients-in-graph-QL-account-response.

The credentialPolicy query provides information about the optional credential policy configured on the credential manager. Note that this query provides global information that isn’t associated to a specific user. This query is experimental and the associated schema may change in future versions of the Curity Identity Server.

Opt-in MFA

The Opt-In MFA information exposed in the account depends on whether the User Management profile has a configured Opt-In MFA action or not:

  • If no Opt-In MFA action is configured on the User Management profile, then this information will be retrieved from the stored account attributes and will not contain the registrable factors or localized descriptions.
  • If an Opt-In MFA action is configured in the User Management profile, then this information will be retrieved from the correct source (stored account attributes or bucket) and can contain the registrable factors or localized descriptions.

Mutations

The possible mutations for account related data available are:

Listing 191 GraphQL Mutations
createAccount(input: CreateAccountInput!): CreateAccountPayload

updateAccountById(input: UpdateAccountByIdInput!): UpdateAccountByIdPayload

validatePasswordAndUpdateAccountById(input: ValidatePasswordAndUpdateAccountByIdInput!): ValidatePasswordAndUpdateAccountByIdPayload

deleteAccountById(input: DeleteAccountByIdInput!): DeleteAccountByIdPayload

deleteLinkFromAccountByAccountId(input: DeleteLinkFromAccountByAccountIdInput!): DeleteLinkFromAccountByAccountIdPayload

deleteDeviceFromAccountByAccountId(input: DeleteDeviceFromAccountByAccountIdInput!): DeleteDeviceFromAccountByAccountIdPayload

deleteOptInMfaFactorFromAccountByAccountId(input: DeleteOptInMfaFactorFromAccountByAccountIdInput!): DeleteOptInMfaFactorFromAccountByAccountIdPayload

resetOptInMfaStateByAccountId(input: ResetOptInMfaStateByAccountIdInput!): ResetOptInMfaStateByAccountIdPayload

addDeviceToAccountByAccountId(input: AddDeviceToAccountByAccountIdInput!): AddDeviceToAccountByAccountIdPayload

updateDeviceFromAccountByAccountId(input: UpdateDeviceFromAccountByAccountIdInput!): UpdateDeviceFromAccountByAccountIdPayload!

startVerifyEmailAddressByAccountId(input: StartVerifyEmailAddressByAccountIdInput!): StartVerifyEmailAddressByAccountIdPayload
completeVerifyEmailAddressByAccountId(input: CompleteVerifyEmailAddressByAccountIdInput!): CompleteVerifyEmailAddressByAccountIdPayload

updatePrimaryEmailAddressByAccountId(input: UpdatePrimaryEmailAddressByAccountIdInput!): UpdatePrimaryEmailAddressByAccountIdPayload

deleteEmailAddressByAccountId(input: DeleteEmailAddressByAccountIdInput!): DeleteEmailAddressByAccountIdPayload

startVerifyPhoneNumberByAccountId(input: StartVerifyPhoneNumberByAccountIdInput!): StartVerifyPhoneNumberByAccountIdPayload
completeVerifyPhoneNumberByAccountId(input: CompleteVerifyPhoneNumberByAccountIdInput!): CompleteVerifyPhoneNumberByAccountIdPayload

updatePrimaryPhoneNumberByAccountId(input: UpdatePrimaryPhoneNumberByAccountIdInput!): UpdatePrimaryPhoneNumberByAccountIdPayload

deletePhoneNumberByAccountId(input: DeletePhoneNumberByAccountIdInput!): DeletePhoneNumberByAccountIdPayload

If a Credential Manager is configured with a credential policy, the following mutations are also available:

Listing 192 GraphQL Credential Policy Rules Mutations
setCredentialPolicyRulesStateByUserName(input: CredentialPolicyRulesStateInput!): CredentialPolicyRulesState

Only the state of rules which are configured in the relevant Credential Policy may be modified.

If a bucket datasource is configured in the User Management profile, the following mutations are also available:

Listing 193 Bucket GraphQL Mutations
deleteBucketByUserName(input: DeleteBucketByUserNameInput!): DeleteBucketByUserNamePayload

Password Reset via Email

The following mutation can be used to start a password reset flow via the sending of an email. This mutation is only available if the User Management profile has an associated HTML Form authenticator.

Listing 194 Password Reset GraphQL Mutations
sendPasswordResetEmail(input: SendPasswordResetInput!): SendPasswordResetPayload

The used Email Sender and templates are the same ones used by the associated HTML Form authenticator.

Account Activation via Email

The following mutation can be used to start an account activation flow via the sending of an email. This mutation is only available if the User Management profile has an associated HTML Form authenticator.

Listing 195 Account Activation GraphQL Mutations
initializeAccountActivation(input: InitializeAccountActivationInput!): InitializeAccountActivationPayload

The used Email Sender and templates are the same ones used by the associated HTML Form authenticator.

Email Address Management

In addition to management via the updateAccountById generic mutation, account email addresses can also be managed via these specialized mutations.

Listing 196 Email Address Management GraphQL Mutations
startVerifyEmailAddressByAccountId(input: StartVerifyEmailAddressByAccountIdInput!): StartVerifyEmailAddressByAccountIdPayload
completeVerifyEmailAddressByAccountId(input: CompleteVerifyEmailAddressByAccountIdInput!): CompleteVerifyEmailAddressByAccountIdPayload

updatePrimaryEmailAddressByAccountId(input: UpdatePrimaryEmailAddressByAccountIdInput!): UpdatePrimaryEmailAddressByAccountIdPayload

deleteEmailAddressByAccountId(input: DeleteEmailAddressByAccountIdInput!): DeleteEmailAddressByAccountIdPayload

These mutations allow for email address verification via the sending and confirmation of one-time-passwords (OTP). The sent emails:

  • Use the default zone Email Provider.
  • Use the templates defined in the templates/core/user-management/device/email folder.

These mutations also enforce domain rules, such as requiring an email address to be verified before setting it as primary, which makes them adequate for usage in self-service scenarios.

Phone Number Management

In addition to management via the updateAccountById generic mutation, account phone numbers can also be managed via these specialized mutations.

Listing 197 Phone Number Management GraphQL Mutations
startVerifyPhoneNumberByAccountId(input: StartVerifyPhoneNumberByAccountIdInput!): StartVerifyPhoneNumberByAccountIdPayload
completeVerifyPhoneNumberByAccountId(input: CompleteVerifyPhoneNumberByAccountIdInput!): CompleteVerifyPhoneNumberByAccountIdPayload

updatePrimaryPhoneNumberByAccountId(input: UpdatePrimaryPhoneNumberByAccountIdInput!): UpdatePrimaryPhoneNumberByAccountIdPayload

deletePhoneNumberByAccountId(input: DeletePhoneNumberByAccountIdInput!): DeletePhoneNumberByAccountIdPayload

These mutations allow for phone number verification via the sending and confirmation of one-time-passwords (OTP) via SMS messages. The sent messages:

  • Use the SMS Sender configured in the associated Authentication profile.
  • Use the message templates defined in the messages/core/en/user-management/device/sms folder.

These mutations also enforce domain rules, such as requiring a phone number to be verified before making it primary, which makes them adequate for usage in self-service scenarios.

TOTP Device Management

The creation of TOTP (Time-based One Time Passwords) devices can be done using the following mutations, which are only available if the User Management profile has a configured TOTP authenticator.

Listing 198 TOTP Device Management GraphQL Mutations
startVerifyTotpDeviceByAccountId(input: StartVerifyTotpDeviceByAccountIdInput!): StartVerifyTotpDeviceByAccountIdPayload
completeVerifyTotpDeviceByAccountId(input: CompleteVerifyTotpDeviceByAccountIdInput!): CompleteVerifyTotpDeviceByAccountIdPayload

TOTP device removal is achieved by using the generic deleteDeviceFromAccountByAccountId mutation.

Passkeys Device Management

The creation of passkeys devices can be done using the following mutations, which are only available if the User Management profile has a configured Passkeys authenticator.

Listing 199 Passkeys Device Management GraphQL Mutations
startVerifyPasskeyByAccountId(input: StartVerifyPasskeyByAccountIdInput!): StartVerifyPasskeyByAccountIdPayload
completeVerifyPasskeyByAccountId(input: CompleteVerifyPasskeyByAccountIdInput!): CompleteVerifyPasskeyByAccountIdPayload

Passkeys device removal is achieved by using the generic deleteDeviceFromAccountByAccountId mutation.

Opt-in MFA

The following mutations are always available to manage account information used by Opt-In MFA action

Listing 200 GraphQL Opt-In MFA mutations
deleteOptInMfaFactorFromAccountByAccountId(input: DeleteOptInMfaFactorFromAccountByAccountIdInput!): DeleteOptInMfaFactorFromAccountByAccountIdPayload

resetOptInMfaStateByAccountId(input: ResetOptInMfaStateByAccountIdInput!): ResetOptInMfaStateByAccountIdPayload

These mutations behave differently depending on whether the User Management profile has a configured Opt-In MFA action or not.

  • If no Opt-In MFA action is configured on the User Management profile, then these mutations assume the Opt-In MFA information is stored inside the account. This will not work correctly if the Opt-In MFA action uses buckets.
  • If an Opt-In MFA action is configured in the User Management profile, then these mutations will use the action configuration to determine the location of the Opt-In MFA information (account attributes or bucket).

If the User Management profile has a configured Opt-In MFA action, then the following additional mutations are also available:

Listing 201 Additional GraphQL Opt-In MFA mutations
startOptInMfaSetupByAccountId(input: StartOptInMfaSetupByAccountIdInput!): StartOptInMfaSetupByAccountIdPayload
completeOptInMfaSetupByAccountId(input: CompleteOptInMfaSetupByAccountIdInput!): CompleteOptInMfaSetupByAccountIdPayload

startOptInMfaResetRecoveryCodesByAccountId(input: StartOptInMfaResetRecoveryCodesByAccountIdInput!): StartOptInMfaResetRecoveryCodesByAccountIdPayload
completeOptInMfaResetRecoveryCodesByAccountId(input: CompleteOptInMfaResetRecoveryCodesByAccountIdInput!): CompleteOptInMfaResetRecoveryCodesByAccountIdPayload

addOptInMfaFactorToAccountByAccountId(input: AddOptInMfaFactorToAccountByAccountIdInput!): AddOptInMfaFactorToAccountByAccountIdPayload

optOutFromOptInMfaByAccountId(input: OptOutFromOptInMfaByAccountIdInput): OptOutFromOptInMfaByAccountIdPayload

The Opt-In MFA factors that can used for setup or added after setup are limited to the following:

  • email authentication factor - can be used if the account has a primary verified email address.
  • sms authentication factor - can be used if the account has a primary verified phone number.
  • totp authentication factor - can be used if
    • The User Management profile has an associated totp authenticator.
    • And the account has at least one TOTP device compatible with that totp authenticator.
  • passkeys authentication factor - can be used if
    • The User Management profile has an associated passkeys authenticator.
    • And the account has at least one Passkeys device compatible with that passkeys authenticator.

Note that the User Management GraphQL API provides mutations to help ensure the previous conditions are met, namely verifying email addresses or adding Passkey devices.

Introspection

GraphQL comes with a schema that can be introspected directly from the endpoint. Most graphql clients knows how to perform this operation and how to interpret the results. It’s important to note that even the introspection of the schema is oauth protected and requires appropriate permissions to be allowed.

Authorization

The GraphQL API requires a valid Access Token from the associated OAuth Profile. This token is used to authorize the request. The authorization is handled by the configured authorization manager. If no authorization manager is configured, then no access will be given. It is recommended to use the groups authorization manager and to provide a value for the groups claim in the access token that maps against the rules in the authorization manager. See how GraphQL operations map to CRUD access operations in authorization manager rules.

Custom Attributes

The User Management profile allows the addition of custom attributes that extend the predefined account type schema. Additional attributes consist of attribute name and attribute type (attribute type represents the data type of an object and must be one of the following: String - text-based attribute, Boolean - true/false, Long - number-based attribute, Object - custom JSON Object). The configured attributes are added to all queries and mutations for an account and are present when introspecting the GraphQL schema. The custom attributes can be configured in the User Management profile settings and are optional in all GraphQL account related queries and mutations.

Data Sources

The currently supported data sources for GraphQL are the JDBC, MongoDB and SCIM 2.0 data sources. There is limited support for DynamoDB, see the limitations.

Limits

The following limits are enforced on inputs

field limit
userName size(min: 1, max: 128)
accountId size(min: 1, max: 128)
externalId size(min: 1, max: 128)
deviceId size(min: 1, max: 128)
acr size(min: 1, max: 512)
otp size(min: 1, max: 16)
email size(min: 1, max: 512)
newPrimaryEmailAddress size(min: 1, max: 512)
emailAddressToDelete size(min: 1, max: 512)
phoneNumber size(min: 1, max: 64)
newPrimaryPhoneNumber size(min: 1, max: 64)
phoneNumberToDelete size(min: 1, max: 64)
profileUrl size(min: 1, max: 512)
displayName size(min: 1, max: 64)
nickName size(min: 1, max: 64)
title size(min: 1, max: 64)
userType size(min: 1, max: 64)
preferredLanguage size(min: 1, max: 16)
locale size(min: 1, max: 16)
timeZone size(min: 1, max: 16)
website size(min: 1, max: 512)
emails list size(min: 0, max: 32)
phoneNumbers list size(min: 0, max: 32)
ims list size(min: 0, max: 32)
photos list size(min: 0, max: 32)
addresses list size(min: 0, max: 32)
groups list size(min: 0, max: 128)
entitlements list size(min: 0, max: 128)
roles list size(min: 0, max: 128)
x509Certificates list size(min: 0, max: 32)
givenName size(min: 0, max: 512)
middleName size(min: 0, max: 512)
familyName size(min: 0, max: 512)
honorificPrefix size(min: 0, max: 512)
honorificSuffix size(min: 0, max: 512)
formatted size(min: 0, max: 1024)
credentialResponseJson size(min: 0, max: 4000)
alias size(min: 0, max: 30)
totp size(min: 0, max: 12)
StringMultiValuedValueInput.value size(min: 0, max: 512)
StringMultiValuedValueInput.type size(min: 0, max: 512)
StringMultiValuedValueInput.display size(min: 0, max: 512)
AddressInput.formatted size(min: 0, max: 2048)
AddressInput.streetAddress size(min: 0, max: 1024)
AddressInput.locality size(min: 0, max: 1024)
AddressInput.region size(min: 0, max: 1024)
AddressInput.postalCode size(min: 0, max: 128)
AddressInput.country size(min: 0, max: 512)
AddressInput.type size(min: 0, max: 128)
AddressInput.display size(min: 0, max: 2048)

More Details

For more details about how to work with the GraphQL APIs see the developer documentation.