Account API

Access info
Endpoint https://account-api.socrate.io/graphql
Required access keys Account Access Key
Pricing Please contact us for details at contact@bitsoftware.ro
Notes To call the service, the access key must be provided in the x-api-key header of the HTTP request. If you are using the GraphQL console, you can view the service’s documentation and schema only after entering an access key. Make sure that the scope of the key allows access to the queries and mutations that you require. For example, to grant the key access to all queries and mutations, the keys’s scope must be set to account-api:query:* account-api:mutation:*.

Usage

The Account API enables you to manage through API calls all SBS entities that are otherwise manageable through the Web user interface in the SBS Console. For example, you can create applications, tenants, or generate service access keys programmatically through API calls.

The Account API is the only SBS service that requires an Account Access Key (AAK). You can generate such a key from the SBS Console, see Generate an Account Access Key.

GraphQL access to the Account API is available either at the endpoint listed at the top of this page, or directly from the SBS Console. To access the GraphQL interface from the SBS Console:

  1. Sign in to the SBS Console.
  2. Click the GraphQL tab.

Queries

account

Returns information about the account that you are currently using. This query may be useful if you have created multiple accounts from the SBS Console and would like to identify the one that you are currently using. In the SBS Console, the current account is the one shown at all times in the dropdown list in the top-right corner of the page. See also SBS accounts and account users.

Arguments

None.

Result

Account type
Attribute Type Description
id ID The unique identifier of the account.
email String The email address associated with the account. NOTE: This field is deprecated.
alias String The name (alias) of the account.
companyInfo CompanyInfo The details of the company that owns this SBS account.
onlineBankingEnabled Boolean Boolean flag which indicates whether online banking is enabled for this account.
onlineBankingBalanceInquiryMonthlyQuota Float Returns the number of monthly online banking balance inquiries allowed for this account. A null or zero value means unlimited balance inquiries are allowed.
onlineBankingTransactionsInquiryMonthlyQuota Float Returns the number of monthly online banking transaction inquiries allowed for this account. A null or zero value means unlimited transaction inquiries are allowed.
createdAt DateTime The date and time when the account was created.
CompanyInfo type
Attribute Type Description
name String The company name.
tin String The company’s tax identification number (TIN).
regNo String The company’s tax registration number.
country CountryCode Enum value that identifies the ISO 3166-2 two-letter country code.
billingAddress Address The company’s billing address information.
email EmailAddress The company’s primary email address.
phone String The company’s primary phone number.
Address type
Attribute Type Description
streetName String The street name.
number String The street number.
additionalAddressDetails String Any additional address details that don’t fit elsewhere.
building String The building identifier, if applicable.
city String The city.
postalCode String The postal code.
region String The region/county/province.
country CountryCode Enum value that identifies the ISO 3166-2 two-letter country code.

accountAccessKeys

Returns the list of Account Access Keys generated for the current account. See also Generate an Account Access Key.

Arguments

None.

Result

The result is an array of objects of type AccountAccessKey.

AccountAccessKey type
Attribute Type Description
email String The email address associated with the account.
alias String The name (alias) of the account.
createdAt DateTime The date and time when the account was created.

accountUserInvitations

Returns the list of account user invitations pending for the current account.

Arguments

None.

Result

The result is an array of objects of type AccountUserInvitation.

accountUsers

Returns the list of account users defined for the current account. See also SBS accounts and account users.

Arguments

None.

Result

The result is an array of objects of type AccountUser.

AccountUser type
Attribute Type Description
id ID The unique identifier of the account user.
provider Provider The identifier of the email provider. Valid values: GOOGLE, MICROSOFT, SOCRATE.
email EmailAddress The email address associated with the account user.
name String The name associated with the account user.
picture Uri The picture’s URI associated with the account user.
createdAt DateTime The date and time when the account user was created.
scope Scope The scope determines the extent of permissions available to the user account. For the syntax rules pertaining to this field, see Update permissions.
isRoot Boolean When true, this value indicates that the current user account is the root account. There can only be one root account user within the same account.

app

Returns information about the application ID supplied as input argument.

Arguments

Attribute Type Description
id ID! Mandatory. The unique identifier of the application.

Result

The result is an object of type App.

App type
Attribute Type Description
id ID The unique identifier of the app.
name String The name of the app.
active Boolean For future use.
createdAt DateTime The date and time when the app was created.
serviceAccessKeys ServiceAccessKey The list of tenant-level service access keys generated for this app.
appLevelServiceAccessKeys ServiceAccessKey The list of app-level service access keys generated for this app.
emailDomain String The email domain associated with this app. See also Register an email subdomain.
googleClientSecret GoogleClientSecret The OAuth 2.0 secrets generated from the Google Cloud Console for this app. See also Configure Google OAuth 2.0 secrets.
azureClientSecret AzureClientSecret The OAuth 2.0 secrets generated from the Microsoft Azure portal for this app. See also Configure Azure OAuth 2.0 secrets.
cognitoClientSecret CognitoClientSecret The OAuth 2.0 secrets generated from Amazon Cognito for this app.
roAnafEfacturaClientSecret RoAnafClientSecret The OAuth 2.0 secrets generated from the ANAF website for usage with E-Factura Service.
roAnafEfacturaAdditionalClientSecrets RoAnafClientSecret Additional OAuth 2.0 secrets generated from the ANAF website for usage with E-Factura Service.
roAnafEfacturaUseTestEnvironment Boolean Indicates whether the app’s environment is “test” or “production” for the purpose of E-Factura reporting. A true value indicates test environment.
roAnafEfacturaUseImplicitClientSecret Boolean Indicates whether your app is configured to use implicit (SBS-managed) ANAF client secrets, or custom client secrets. Valid values: true - your app uses SBS-managed client secrets for E-Factura; false or null - your app uses custom ANAF client secrets. See also Configure ANAF OAuth 2.0 secrets.
roAnafEtransportClientSecret RoAnafClientSecret The OAuth 2.0 secrets generated from the ANAF website for usage with E-Transport Service.
roAnafEtransportAdditionalClientSecrets RoAnafClientSecret Additional OAuth 2.0 secrets generated from the ANAF website for usage with E-Transport Service.
roAnafEtransportUseTestEnvironment Boolean Indicates whether the app’s environment is “test” or “production” for the purpose of E-Transport reporting. A true value indicates test environment.
roAnafEtransportUseImplicitClientSecret Boolean Indicates whether your app is configured to use implicit (SBS-managed) ANAF client secrets, or custom client secrets. Valid values: true - your app uses SBS-managed client secrets for E-Transport; false or null - your app uses custom ANAF client secrets. See also Configure ANAF OAuth 2.0 secrets.
onlineBankingUseTestEnvironment Boolean Indicates whether the app’s environment is “test” or “production” for the purpose of online banking. A true value indicates test environment.
onlineBankingUseImplicitSettings Boolean Indicates whether your app is configured to use implicit online banking settings. Valid values: true - your app uses implicit settings for online banking; false or null - your app uses custom online banking settings as provided by the onlineBankingSettings property.
onlineBankingSettings OnlineBankingSettings This property defines custom online banking settings that are used if onlineBankingUseImplicitSettings is false.
emailIdentities [EmailIdentity] The email identities defined at application level. See also Verify an email identity at application level.
domainIdentities(filter: DomainIdentitiesFilter) [DomainIdentity] The domain identities defined at application level. See also Verify a domain identity at application level.
emailSenders [EmailAddress] The email addresses authorized to send email at application level.
ServiceAccessKey type
Attribute Type Description
privateKey String The private (secret) part of the access key. This is a sensitive value that grants access to a particular service and should be stored securely. Note that the prefix of the key identifies whether it’s an app-level or tenant-level key. Specifically, app-level keys begin with app- while tenant-level keys begin with ten-.
publicKey String The public part of the access key.
appId ID The identifier of the app to which this key belongs.
app App The App object to which this key belongs.
tenantId ID The identifier of the tenant to which this key belongs. Applicable only if the current access key is a tenant-level access key.
tenant Tenant The Tenant object to which this key belongs. Applicable only if the current access key is a tenant-level access key.
active Boolean For future use.
description String The description of this access key.
scope Scope The scope defines the extent of permissions available to the bearer of this access key. See also Restrict access to services.
createdAt DateTime The date and time when the key was created.
Tenant type
Attribute Type Description
id ID The unique identifier of the tenant.
name String The tenant’s name.
active Boolean Specifies if the tenant is active. This field is for future use.
onlineBankingEnabled Boolean Boolean flag which indicates whether online banking is enabled for this tenant.
onlineBankingBalanceInquiryMonthlyQuota Float Returns the number of monthly online banking balance inquiries allowed for this tenant. A null or zero value means unlimited balance inquiries are allowed.
onlineBankingTransactionsInquiryMonthlyQuota Float Returns the number of monthly online banking transaction inquiries allowed for this tenant. A null or zero value means unlimited transaction inquiries are allowed.
createdAt DateTime The date and time when the tenant was created.
serviceAccessKeys [ServiceAccessKey] The array of ServiceAccessKey objects associated with this tenant.
serviceAccessDenials [ServiceAccessDenial] The array of ServiceAccessDenial objects associated with this tenant. See also Service Access Denials.
ServiceAccessDenial type
Attribute Type Description
id ID The unique identifier of the service access denial.
tenantId ID The identifier of the tenant affected by this service access denial.
appId ID The identifier of the app affected by this service access denial.
app App The app details of of the app affected by this service access denial.
scope Scope The scope defines which queries and mutations are actually being denied.
reason String The message returned to the API caller which attempts to access a denied resource. This should be explanatory enough to avoid misunderstanding.
createdAt DateTime The date and time when the service access denial was created.
GoogleClientSecret type
Attribute Type Description
web GoogleClientSecretWeb This field groups together all secrets downloaded from the Google Cloud Console.
GoogleClientSecretWeb type
Attribute Type Description
client_id ID The ID of the OAuth 2.0 client as it appears in the Google Cloud Console.
project_id ID The project ID of the OAuth 2.0 client as it appears in the Google Cloud Console.
auth_uri String The authorization URI of the OAuth 2.0 client as it appears in the Google Cloud Console.
token_uri String The token URI of the OAuth 2.0 client as it appears in the Google Cloud Console.
auth_provider_x509_cert_url String The URL of the authorization provider’s certificate, as it appears in the Google Cloud Console.
client_secret String The client secret of the OAuth 2.0 client, as it appears in the Google Cloud Console.
redirect_uri Uri The redirect URI of the OAuth 2.0 client, as it appears in the Google Cloud Console.
javascript_origins [String] An array of HTTP origins that host your application, as they appear in the Google Cloud Console.
AzureClientSecret type
Attribute Type Description
web AzureClientSecretWeb This field groups together all secrets downloaded from the Azure Portal.
AzureClientSecretWeb type
Attribute Type Description
tenant_id ID The ID of the tenant as it appears in the Azure Portal.
application_id ID The ID of the application as it appears in the Azure Portal.
client_secret String The client secret of the OAuth 2.0 client, as it appears in the Azure Portal.
redirect_uri Uri The redirect URI of the OAuth 2.0 client, as it appears in the Azure Portal.
CognitoClientSecret type
Attribute Type Description
web CognitoClientSecretWeb This field groups together all application’s OAuth 2.0 secrets obtained from Amazon Cognito.
CognitoClientSecretWeb type
Attribute Type Description
userPoolId String! Mandatory. The ID of the Amazon Cognito User Pool.
clientId ID! Mandatory. The Client ID from Amazon Cognito.
RoAnafClientSecret type
Attribute Type Description
clientId String The ID of the OAuth 2.0 client generated on the ANAF portal.
clientSecret String The client secret of the OAuth 2.0 client generated on the ANAF portal. Note that, if roAnafEfacturaUseImplicitClientSecret or roAnafEtransportUseImplicitClientSecret is true, your app’s ANAF client secrets are managed by SBS, in which case this field will return a null value.
oauthCallback String The OAuth 2.0 callback URL generated on the ANAF portal.
OnlineBankingSettings type
Attribute Type Description
oauthCallback Uri A custom defined OAuth 2.0 callback URI. The user’s browser will be redirected to this URI after completing the online banking authorization process.
EmailIdentity type
Attribute Type Description
address String The email address intended for use in the “From” field when sending email through the Email Service.
status IdentityVerificationStatus The verification status for the email address. Valid values: VERIFIED, PENDING.
DomainIdentity type
Attribute Type Description
domain Domain The Internet domain, for example example.org.
status IdentityVerificationStatus Indicates whether the domain has been verified or not. This is an enum with the following possible values: PENDING, VERIFIED.
dnsRecords [DnsRecord] This property returns an array of records of type DnsRecord. All these records must be added to the domain’s zone records in order for the domain to become VERIFIED.
DnsRecord type
Attribute Type Description
type DnsRecordType Specifies the type of the DNS record. This is an enum with only one possible value: CNAME.
name String The DNS record name.
value String The DNS record value.
DomainIdentitiesFilter type
Attribute Type Description
status IdentityVerificationStatus Enables filtering domain identities by their verification status. This is an enum type with the following possible values: VERIFIED, PENDING.

apps

Returns information about multiple applications. The filtering options are supplied as input argument.

Arguments

Attribute Type Description
filter AppsFilter Optional. Provides filtering options.
nextToken String Optional argument used to fetch the next set of query results. This value can be obtained from the nextToken attribute of the AppsResult type.
AppsFilter type
Attribute Type Description
active Boolean Optional. When set to true, the result will include only active applications. NOTE: This field is for future use.

Result

The result is an object of type AppsResult.

AppsResult type
Attribute Type Description
items [App] The array of App objects that match the filter criteria.
nextToken String If null, then the query has reached the end of the list of results that match the query criteria. If not null, then use this value in the nextToken input argument, with the same filter, to fetch the next set of results.

calls

Returns usage statistics about SBS services. You can query, for example, how many times a particular query or mutation of a particular service was called.

Arguments

Attribute Type Description
filter CallsFilter Optional. Provides filtering options.
nextToken String Optional argument used to fetch the next set of query results. This value can be obtained from the nextToken attribute of the CallsResult type.
limit Int Optional. The limit defines the maximum number of records that will be retrieved in the same call.
CallsFilter type
Attribute Type Description
from DateTime! Mandatory. The call will return statistics beginning with this date.
to DateTime Optional. When provided, the call will return statistics up to this date only.
service ServiceCode! Mandatory. The service code specifies the service for which you would like to collect statistics. To obtain all available service codes at application or tenant level, run the services query. The service code of the Account API is account-api.
operationType OperationType! Mandatory. Specifies the operation type for which statistics should be returned. Valid values: query, mutation.
field Field Optional. Specifies the name of the query or mutation for which statistics should be returned.
appId ID Optional. When an appId is specified, only statistics for this app will be returned. It is meaningful to supply this value only if service requires an application-level access key.
tenantId ID Optional. When a tenantId is specified, only statistics for this tenant will be returned. It is meaningful to supply this value only if service requires a tenant-level access key.

Result

The result is an object of type CallsResult.

CallsResult type
Attribute Type Description
items [CallsValue] The array of CallsValue objects that match the filter criteria.
nextToken String If null, then the query has reached the end of the list of results that match the query criteria. If not null, then use this value in the nextToken input argument, with the same filter, to fetch the next set of results.
CallsValue type
Attribute Type Description
field Field The query or mutation involved in this statistic.
appId ID The ID of the app involved in this statistic.
tenantId ID The ID of the tenant involved in this statistic.
count Float Specifies the actual number of calls that took place, taking into account any filtering options that were set.

portalUser

Returns an SBS Portal user by ID.

Arguments

Attribute Type Description
userId String Mandatory. The ID of the portal user to retrieve.

Result

The result is an object of type PortalUser.

portalUserInvitations

Returns the list of SBS portal user invitations pending for the current account.

Arguments

None.

Result

The result is an array of objects of type PortalUserInvitation.

portalUsers

Returns a list of SBS Portal users, along with their permissions.

Arguments

Attribute Type Description
filter PortalUsersFilter Optional. Provides filtering options.
nextToken String Optional argument used to fetch the next set of query results. This value can be obtained from the nextToken attribute of the CallsResult type.
PortalUsersFilter type
Attribute Type Description
provider Provider Optional. When provided, only users having this email provider will be returned in the results. Valid values: GOOGLE, MICROSOFT, SOCRATE.
email EmailAddress Optional. When provided, the call will return only the user with this email address.

Result

The result is an object of type PortalUsersResult.

PortalUsersResult type
Attribute Type Description
items [PortalUser] The array of PortalUser objects that match the filter criteria.
nextToken String If null, then the query has reached the end of the list of results that match the query criteria. If not null, then use this value in the nextToken input argument, with the same filter, to fetch the next set of results.
PortalUser type
Attribute Type Description
userId ID The unique identifier of the portal user.
provider Provider The email provider of the portal user. Valid values: GOOGLE, MICROSOFT, SOCRATE.
email EmailAddress The email address of the portal user.
name String The name of the portal user.
picture Uri The URI of the picture associated with this portal user.
createdAt DateTime The date and time when this portal user was created.
permissions [Permission] The list of permissions assigned to the portal user, as an array of Permission objects.
Permission type
Attribute Type Description
appId ID The unique identifier of the app to which the permission applies.
app App The object of type App to which the permission applies.
tenantId ID The unique identifier of the tenant to which the permission applies.
tenant Tenant The object of type Tenant to which the permission applies.
scope Scope The scope of the permission. For the syntax rules, see Restrict access to services.
createdAt DateTime The date and time when the permission was created.

serviceAccessKeys

Returns the list of service access keys generated either at application level or at tenant-level (for a tenant-app combination). Each private key begins with a string that identifies the key type. If the private key is application-level, it begins with app-. If the key is tenant-level, it begins with ten-.

Arguments

Attribute Type Description
filter ServiceAccessKeysFilter Optional. Provides filtering options.
nextToken String Optional argument used to fetch the next set of query results. This value can be obtained from the nextToken attribute of the CallsResult type.
ServiceAccessKeysFilter type
Attribute Type Description
appId ID Optional. When provided, the query will return only keys that belong to this app.
tenantId ID Optional. When provided, the query will return only keys that belong to this tenant.
publicKey String Optional. When provided, the query will return only the service access key identified by this public key.

Result

ServiceAccessKeysResult type
Attribute Type Description
items [ServiceAccessKey] The array of ServiceAccessKey objects that match the filter criteria.
nextToken String If null, then the query has reached the end of the list of results that match the query criteria. If not null, then use this value in the nextToken input argument, with the same filter, to fetch the next set of results.

services

Returns a list of all services exposed by the Socrate Business Services API. This query is useful when you need to find out the service code of a particular service, for example, when setting permissions (scope) or querying usage.

Arguments

Attribute Type Description
accessLevel ServiceAccessLevel! Mandatory. Valid values: APP, TENANT. Use APP to retrieve services that require an app-level service access key. Use TENANT to retrieve services that require a tenant-level service access key.

Result

An array of service codes, for example:

{
  "data": {
    "services": [
      "oauth-api",
      "public-holidays-api",
      "user-management-api",
      "vat-validator-api"
    ]
  }
}

Example

The following query retrieves all service codes that require a tenant-level service access key:

query services($accessLevel:ServiceAccessLevel!) {
  services(accessLevel:$accessLevel) 
}

With variables:

{
  "accessLevel": "TENANT"
}

tenant

Returns the tenant matching the ID supplied as input argument.

Arguments

Attribute Type Description
id ID Mandatory. The ID of the tenant to retrieve.

Result

The result is an object of type Tenant.

tenants

Returns the list of tenants matching the filter criteria. If no filter is specified, all tenants of the current account will be returned in the result.

Arguments

Attribute Type Description
filter TenantsFilter Optional. Provides filtering options.
nextToken String Optional argument used to fetch the next set of query results. This value can be obtained from the nextToken attribute of the CallsResult type.
TenantsFilter type
Attribute Type Description
active Boolean Optional. When provided, the query will return only active tenants. This field is currently for future use.
name String Optional. When provided, the query will return only tenants that match this name.

Result

The result is an array of objects of type TenantsResult.

TenantsResult type
Attribute Type Description
items [Tenant] The array of Tenant objects that match the filter criteria.
nextToken String If null, then the query has reached the end of the list of results that match the query criteria. If not null, then use this value in the nextToken input argument, with the same filter, to fetch the next set of results.

usage

Returns information about usage of SBS services. Querying usage is meaningful only for those services that have usage measurement types (counters). Currently, the following services have counters:

  • e-Factura Service
  • e-Transport Service
  • Online Banking Service
  • Tax Declarations Service

Arguments

Attribute Type Description
filter UsageMeasurementFilter Optional. Provides filtering options.
nextToken String Optional argument used to fetch the next set of query results. This value can be obtained from the nextToken attribute of the UsageMeasurementResult type.
limit Int Optional. The limit defines the maximum number of records that will be retrieved in the same call.
UsageMeasurementFilter type
Attribute Type Description
from DateTime! Mandatory. When provided, the call will return usage beginning with this date.
to DateTime Optional. When provided, the call will return usage up to this date only.
service ServiceCode! Mandatory. The service code specifies the service for which you would like to collect usage. To obtain all available service codes at application or tenant level, run the services query. The service code of the Account API is account-api.
type TypeCode! Mandatory. Specifies the usage type. Valid values depend on the service argument. Run the usageMeasurementTypes query to obtain usage measurement types applicable for each service.
appId ID Optional. When an appId is specified, only usage for this app will be returned.
tenantId ID Optional. When a tenantId is specified, only usage for this tenant will be returned.
environment Environment Optional. An enum with the following valid values: TEST, PRODUCTION. If specified, only usage for this environment will be returned. Supplying this filter is meaningful only for services that have test and production environments (currently, ro-efactura-api, ro-etransport-api, and online-banking-api).

Result

The result is an object of type UsageMeasurementResult.

UsageMeasurementResult type
Attribute Type Description
items [MeasurementValue] The array of MeasurementValue objects that match the filter criteria.
nextToken String If null, then the query has reached the end of the list of results that match the query criteria. If not null, then use this value in the nextToken input argument, with the same filter, to fetch the next set of results.
MeasurementValue type
Attribute Type Description
value String The value of the statistic.
date Date The date relevant to this statistic.
app App The app to which this statistic applies.
tenant Tenant The tenant to which this statistic applies.

usageFilters

When you run the usage query, some filters are not applicable, depending on the service supplied as input. This query indicates which filters apply to and are meaningful for the service supplied as input.

Arguments

Attribute Type Description
service ServiceCode! Mandatory. The code of the service for which you would to obtain information. You can obtain the service code of each service by running the services query.

Result

UsageFilters type
Attribute Type Description
appId Boolean True if this service is filterable by an appId, false otherwise.
tenantId Boolean True if this service is filterable by a tenantId, false otherwise.
environment Boolean True if this service is filterable by an environment, false otherwise.

usageMeasurementTypes

Returns the measurement types (names of usage counters) supported by a given service. This is useful for those services that have usage counters, such as ro-efactura-api, ro-etransport-api, and others.

Arguments

Attribute Type Description
service ServiceCode! Mandatory. The code of the service for which you are requesting measurement types. You can obtain the service code from the endpoint URL of each service, by extracting from the URL the string part after https:// and before .socrate. For example, if the URL is https://tax-declarations-api.socrate.xyz/graphql, then the service code is tax-declarations-api.

Result

An array of type codes. Each type code is the name of the measurement type. For example, if the service supplied as input is tax-declarations-api, the returned type code is CSV_FILE_LINES.

version

Returns the API version.

Mutations

addEmailSender

Adds an email address to the list of authorized email senders for this app. Note that you can add an email sender only if the domain of the email address is a domain identity created through the verifyDomainIdentity mutation.

Arguments

Attribute Type Description
appId ID! Mandatory. The ID of the app where the authorized email sender is to be added.
address EmailAddress! Mandatory. The authorized email address to be added.

Result

The result of this mutation is an email address of type EmailAddress.

createApp

Creates a new application.

Arguments

Attribute Type Description
input CreateAppInput! Mandatory. Provides input data to the mutation.
CreateAppInput type
Attribute Type Description
name String! Mandatory. The name of the app to be created. The app name must be unique within the boundaries of the account.

Result

See the App type.

createTenant

Creates a new tenant.

Arguments

Attribute Type Description
input CreateTenantInput! Mandatory. Provides input data to the mutation.
CreateTenantInput type
Attribute Type Description
name String! Mandatory. The name of the tenant to be created. The tenant name must be unique within the boundaries of the account.

Result

See the Tenant type.

deleteAccountAccessKey

Deletes an account access key.

Arguments

Attribute Type Description
publicKey String! Mandatory. The public key associated with the account access key to be deleted.

Result

See the AccountAccessKey type.

deleteAppLevelServiceAccessKey

Deletes an application-level service access key.

Arguments

Attribute Type Description
input DeleteAppLevelServiceAccessKeyInput! Mandatory. Provides input data to the mutation.
DeleteAppLevelServiceAccessKeyInput type
Attribute Type Description
appId ID! Mandatory. The identifier of the app where the service access key is applicable.
publicKey String! Mandatory. The public key of the service access key.

Result

See the ServiceAccessKey type.

deleteDomainIdentity

Deletes a domain identity.

Arguments

Attribute Type Description
appId ID! Mandatory. The identifier of the app from which the domain identity is being deleted.
domain Domain! Mandatory. The Internet domain of the identity to be deleted.

Result

See the DomainIdentity.

deleteEmailIdentity

Deletes an email identity.

Arguments

Attribute Type Description
appId ID! Mandatory. The identifier of the app from which the email identity is being deleted.
address EmailAddress! Mandatory. The email address to be deleted.

Result

See the EmailIdentity.

deleteServiceAccessKey

Deletes a service access key.

Arguments

Attribute Type Description
input DeleteServiceAccessKeyInput! Mandatory. Provides input data to the mutation.
DeleteServiceAccessKeyInput type
Attribute Type Description
appId ID! Mandatory. The identifier of the app where the service access key is applicable.
tenantId ID! Mandatory. The identifier of the tenant where the service access key is applicable.
publicKey String! Mandatory. The public key of the service access key.

Result

See the ServiceAccessKey type.

denyServiceAccess

A service access denial prevents a tenant from running the designated set of queries and mutations. This is a quick way to block only a very specific resource temporarily without modifying the tenant’s service access key. You can revoke existing denials through the revokeServiceAccessDenial mutation. See also Service access denials.

Arguments

Attribute Type Description
input DenyServiceAccessInput! Mandatory. Provides input data to the mutation.
DenyServiceAccessInput type
Attribute Type Description
tenantId ID! The ID of the tenant whose access to the resource must be blocked.
appId ID! The ID of the app where the denial is active.
scope Scope! The list of queries and/or mutations that must be blocked. For example, the scope email-api:mutation:sendMessage will prevent the tenant from being able to call the sendMessage mutation of the Email Service. For syntax details, see Restrict access to services.
reason String! The message that should appear to the API caller when they attempt to access the blocked resource.

Result

See the ServiceAccessDenial type.

generateAccountAccessKey

Generates an account access key. See also Generate a account access key.

Arguments

Attribute Type Description
input GenerateAccountAccessKeyInput! Mandatory. Provides input data to the mutation.
GenerateAccountAccessKeyInput type
Attribute Type Description
active Boolean Optional, for future use.
description String Optional. Provides a description for the generated key.
scope Scope Optional. Defines the extent of permissions available to the bearer of the key. For syntax details, see Restrict access to services.

Result

See the AccountAccessKey type.

generateAppLevelServiceAccessKey

Generates a service access key at application level. See also Generate an application-level service access key.

Arguments

Attribute Type Description
input GenerateAppLevelServiceAccessKeyInput! Mandatory. Provides input data to the mutation.
GenerateAppLevelServiceAccessKeyInput type
Attribute Type Description
appId ID! Mandatory. The identifier of the app where the service access key is applicable.
active Boolean Optional, for future use.
description String Optional. Provides a description for the generated key.
scope Scope Optional. Defines the extent of permissions available to the bearer of the key. For syntax details, see Restrict access to services.

Result

See the ServiceAccessKey type.

generateServiceAccessKey

Generates a tenant-level service access key. See also Generate a service access key.

Arguments

Attribute Type Description
input GenerateServiceAccessKeyInput! Mandatory. Provides input data to the mutation.
GenerateServiceAccessKeyInput type
Attribute Type Description
appId ID! Mandatory. The identifier of the app where the service access key is applicable.
tenantId ID! Mandatory. The identifier of the tenant where the service access key is applicable.
active Boolean Optional, for future use.
description String Optional. Provides a description for the generated key.
scope Scope Optional. Defines the extent of permissions available to the bearer of the key. For syntax details, see Restrict access to services.

Result

See the ServiceAccessKey type.

inviteAccountUser

Sends an invitation to the email address supplied as input. If the user accepts the invitation, they will be added as a new account user with access to the SBS Console (for the SBS account that sent the invitation). The extent of permissions available to the new user are defined through the scope input parameter.

Arguments

Attribute Type Description
input InviteAccountUserInput! Mandatory. Provides input data to the mutation.
InviteAccountUserInput type
Attribute Type Description
provider Provider Optional. If you specify a provider, the user will be able to complete the invitation and become an account user only if their email address is from that provider. Valid values: GOOGLE, MICROSOFT, SOCRATE.
email EmailAddress! Mandatory. Specifies the email address of the account user to be invited.
scope Scope! Mandatory. Specifies the extent of permissions available to the new user. For example, to grant the user permissions to view all data across the SBS Console but not modify it, enter account-api:query:*. For more information, see Defining scope in GraphQL.
message String Optional. A custom text message to be included in the invitation email.

Result

AccountUserInvitationType type
Attribute Type Description
id ID The unique identifier of the invitation.
provider Provider The identifier of the email provider specified when running the inviteAccountUser mutation. Possible values: GOOGLE, MICROSOFT, SOCRATE.
email EmailAddress The email address associated with the invitation.
scope Scope The extent of permissions available to the user.

Example

mutation inviteAccountUser($input:InviteAccountUserInput!) {
  inviteAccountUser(input:$input) {
        id
        provider
        email
  }
}

{
  "input": {
    "provider": "SOCRATE",
    "email": "user@example.org",
    "scope": "account-api:query:*"
  }
}

invitePortalUser

Sends an invitation to the email address supplied as input. If the user accepts the invitation, they will be added as a new user with access to the SBS Portal.

Arguments

Attribute Type Description
input InvitePortalUserInput! Mandatory. Provides input data to the mutation.
InvitePortalUserInput type
Attribute Type Description
provider Provider Optional. If you specify a provider, the user will be able to complete the invitation and become an SBS Portal user only if their email address is from that provider. Valid values: GOOGLE, MICROSOFT, SOCRATE.
email EmailAddress! Mandatory. Specifies the email address of the user to be invited.
scope [PermissionInput]! Mandatory. Specifies the extent of permissions available to the new user. Since a user may need access to multiple SBS apps and tenants, multiple permission sets can be assigned, one for each app-tenant combination. See PermissionInput.
message String Optional. A custom text message to be included in the invitation email.

Result

PortalUserInvitationType type
Attribute Type Description
id ID The unique identifier of the invitation.
provider Provider The identifier of the email provider specified when running the invitePortalUser mutation. Possible values: GOOGLE, MICROSOFT, SOCRATE.
email EmailAddress The email address associated with the invitation.
permissions [PortalUserInvitationPermission] The array of permissions assigned to the portal user. Each array item is of type PortalUserInvitationPermission.
PortalUserInvitationPermission type
Attribute Type Description
appId ID The unique identifier of the app where scope applies.
tenantId ID The unique identifier of the tenant where scope applies.
scope Scope The actual scope (extent of permissions) available to the user for this app and tenant combination. See Defining scope in GraphQL.

registerAppSubdomain

This mutation is useful if you would like to configure your application to receive email at some specified address. The email subdomain registered via this query becomes part of the email address at which you can receive email.

Arguments

Attribute Type Description
input RegisterAppSubdomainInput! Mandatory. Provides input data to the mutation.
RegisterAppSubdomainInput type
Attribute Type Description
appId ID! Mandatory. The identifier of the app for which you are registering the email subdomain.
subdomain String! Mandatory. The actual email subdomain to be registered.

Result

AppSubDomain type
Attribute Type Description
appId ID The identifier of the application whose email subdomain was registered.
subdomain String The email subdomain that was registered.
emailDomain String This string identifies the part of the email after the “@” character, excluding the tenant’s subdomain. The tenant’s subdomain must be registered through the registerSubdomain mutation of the Email Service individually for each tenant.

removeAccountUser

Deletes an account user.

Arguments

Attribute Type Description
id ID! Mandatory. The ID of the account user to be deleted.

Result

See the AccountUser type.

removeAccountUserInvitation

Removes a pending SBS account invitation.

Arguments

Attribute Type Description
id ID! Mandatory. The ID of the pending SBS account invitation.

Result

See the AccountUserInvitation type.

removeEmailSender

Removes an email address from the list of authorized email senders for this app.

Arguments

Attribute Type Description
appId ID! Mandatory. The ID of the app from where the authorized email sender is to be removed.
address EmailAddress! Mandatory. The authorized email address to be removed.

Result

The result of this mutation is an email address of type EmailAddress.

removePortalUser

Deletes a portal user.

Arguments

Attribute Type Description
id ID! Mandatory. The ID of the portal user to be deleted.

Result

See the PortalUser type.

removePortalUserInvitation

Removes a pending SBS Portal user invitation.

Arguments

Attribute Type Description
id ID! Mandatory. The ID of the pending portal user invitation.

Result

See the PortalUserInvitation type.

removePortalUserPermission

Removes permissions previously granted to a portal user.

Arguments

Attribute Type Description
userId ID! Mandatory. The ID of the portal user whose permissions must be removed.
permissionKey PermissionKeyInput! Mandatory. A permission key defines the unique app-tenant combination that was specified when creating the permission.
PermissionKeyInput type
Attribute Type Description
appId ID! Mandatory. Specifies the identifier of the app where permissions are applicable.
tenantId ID Optional. Specifies the identifier of the tenant where permissions are applicable.

Result

See the PortalUser type.

revokeServiceAccessDenial

Revokes (deletes) a service access denial that is in effect for a given tenant/app combination. This mutation is the reverse of the denyServiceAccess mutation.

Arguments

Attribute Type Description
input RevokeServiceAccessDenialInput! Mandatory. Provides input data to the mutation.
RevokeServiceAccessDenialInput type
Attribute Type Description
tenantId ID! Mandatory. The ID of the tenant where the service access denial applies.
appId ID! Mandatory. The ID of the app where the service access denial applies.
denialId ID! Mandatory. The ID of the service access denial record.

Result

See the ServiceAccessDenial type.

updateAccountUser

Updates the SBS Console permissions (scope) of an existing account user.

Arguments

Attribute Type Description
id ID! Mandatory. The ID of the account user to be updated.
input UpdateAccountUserInput! Mandatory. Provides input data to the mutation.
UpdateAccountUserInput type
Attribute Type Description
scope Scope Optional. Specifies the extent of permissions available to the account user. See Restrict access to services for more information.

Result

See the AccountUser type.

updateApp

Updates an application’s details (such as name or OAuth 2.0 secrets).

Arguments

Attribute Type Description
input UpdateAppInput! Mandatory. Provides input data to the mutation.
UpdateAppInput type
Attribute Type Description
name String Optional. Specifies the new name of the app.
active Boolean Optional, for future use. Activates or deactivates the app.
googleClientSecret GoogleClientSecretInput Optional. Provides input data used to update the application’s Google OAuth 2.0 secrets.
azureClientSecret AzureClientSecretInput Optional. Provides input data used to update the application’s Azure OAuth 2.0 secrets.
cognitoClientSecret CognitoClientSecretInput Optional. Provides input data used to update the application’s Cognito OAuth 2.0 secrets.
roAnafEfacturaClientSecret RoAnafClientSecretInput Optional. Provides input data used to update the application’s ANAF OAuth 2.0 secrets used to authorize E-Factura calls. You do not need to supply a value for this field if roAnafEfacturaUseImplicitClientSecret is true.
roAnafEfacturaAdditionalClientSecrets RoAnafClientSecretInput Optional. Used when you need multiple callback URLs for ANAF OAuth 2.0 authorization. See Managing additional ANAF OAuth 2.0 secrets.
roAnafEfacturaUseTestEnvironment Boolean Optional. Set this option to true if the app should use the RO ANAF test environment instead of production, for the purpose of E-Factura reporting.
roAnafEfacturaUseImplicitClientSecret Boolean Optional. Set this option to true if your app should use implicit (SBS-managed) ANAF client secrets for E-Factura reporting. See also Configure ANAF OAuth 2.0 secrets.
roAnafEtransportClientSecret RoAnafClientSecretInput Optional. Provides input data used to update the application’s ANAF OAuth 2.0 secrets used to authorize E-Transport calls. You do not need to supply a value for this field if roAnafEtransportUseImplicitClientSecret is true.
roAnafEtransportAdditionalClientSecrets RoAnafClientSecretInput Optional. Used when you need multiple callback URLs for ANAF OAuth 2.0 authorization. See Managing additional ANAF OAuth 2.0 secrets.
roAnafEtransportUseTestEnvironment Boolean Optional. Set this option to true if the app should use the RO ANAF test environment instead of production, for the purpose of E-Transport reporting.
roAnafEfacturaUseImplicitClientSecret Boolean Optional. Set this option to true if your app should use implicit (SBS-managed) ANAF client secrets for E-Transport reporting. See also Configure ANAF OAuth 2.0 secrets.
onlineBankingUseTestEnvironment Boolean Optional. Set this option to true if your app should use the test environment for online banking.
onlineBankingUseImplicitSettings Boolean Optional. Set this option to true if your app should use implicit (default) online banking settings. A false value means the app will use custom online banking settings, as defined through the onlineBankingSettings input.
onlineBankingSettings OnlineBankingSettingsInput Conditional. This property defines custom online banking settings. It is mandatory if onlineBankingUseImplicitSettings is false.
GoogleClientSecretInput type
Attribute Type Description
web GoogleClientSecretWeb This field groups together all application’s OAuth 2.0 secrets downloaded from the Google Cloud Console.
GoogleClientSecretWebInput type
Attribute Type Description
client_id ID! Mandatory. The ID of the OAuth 2.0 client as it appears in the Google Cloud Console.
project_id ID Optional. The project ID of the OAuth 2.0 client as it appears in the Google Cloud Console.
auth_uri String! Mandatory. The authorization URI of the OAuth 2.0 client as it appears in the Google Cloud Console.
token_uri String! Mandatory. The token URI of the OAuth 2.0 client as it appears in the Google Cloud Console.
auth_provider_x509_cert_url String! Mandatory. The URL of the authorization provider’s certificate, as it appears in the Google Cloud Console.
client_secret String! Mandatory. The client secret of the OAuth 2.0 client, as it appears in the Google Cloud Console.
redirect_uri Uri Optional. The redirect URI of the OAuth 2.0 client, as it appears in the Google Cloud Console.
javascript_origins [String] Optional. An array of HTTP origins that host your application, as they appear in the Google Cloud Console.
AzureClientSecretInput type
Attribute Type Description
web AzureClientSecretWebInput This field groups together all application’s OAuth 2.0 secrets downloaded from the Azure portal.
AzureClientSecretWebInput type
Attribute Type Description
application_id ID! Mandatory. The ID of the application as it appears in the Azure Portal.
tenant_id ID Optional. The ID of the tenant as it appears in the Azure Portal.
client_secret String Optional. The client secret of the OAuth 2.0 client, as it appears in the Azure Portal.
redirect_uri Uri Optional. The redirect URI of the OAuth 2.0 client, as it appears in the Azure Portal.
CognitoClientSecretInput type
Attribute Type Description
web CognitoClientSecretWebInput This field groups together all application’s OAuth 2.0 secrets obtained from Amazon Cognito.
CognitoClientSecretWebInput type
Attribute Type Description
userPoolId String! Mandatory. The ID of the Amazon Cognito User Pool.
clientId ID! Mandatory. The Client ID from Amazon Cognito.
RoAnafClientSecretInput type

This type has the same structure as the RoAnafClientSecret type.

OnlineBankingSettingsInput type
Attribute Type Description
oauthCallback Uri! A custom defined OAuth 2.0 callback URI. The user’s browser will be redirected to this URI after completing the online banking authorization process.

Result

See the App type.

updateCompanyInfo

Updates the company information of the company that owns the current SBS account.

Arguments

Attribute Type Description
input CompanyInfoInput The company data to be updated.
CompanyInfoInput type
Attribute Type Description
name String! The company name.
tin String The company’s tax identification number (TIN).
regNo String! The company’s tax registration number.
country CountryCode! Enum value that identifies the ISO 3166-2 two-letter country code.
billingAddress AddressInput! The company’s billing address information.
email EmailAddress! The company’s primary email address.
phone String The company’s primary phone number.
AddressInput type
Attribute Type Description
streetName String! The street name.
number String! The street number.
additionalAddressDetails String Any additional address details that don’t fit elsewhere.
building String The building identifier, if applicable.
city String! The city.
postalCode String The postal code.
region String! The region/county/province.
country CountryCode! Enum value that identifies the ISO 3166-2 two-letter country code.

Result

See the CompanyInfo type.

setPortalUserPermission

Arguments

Attribute Type Description
userID ID! Mandatory. The ID of the portal user whose permissions are to be updated.
permission PermissionInput! Mandatory. Defines the extent of permissions granted to the portal user.
PermissionInput type
Attribute Type Description
appId ID! Mandatory. Identifies the app where permissions are applicable.
tenantId ID! Mandatory. Identifies the tenant where permissions are applicable.
scope Scope! Mandatory. Specifies the actual extent of permissions granted. For example, to grant the user permissions to view all email for the given app and tenant but not modify it, enter email-api:query:*. For more information, see Defining scope in GraphQL.

Result

See the PortalUser type.

updateServiceAccessKey

Updates a tenant-level service access key.

Arguments

Attribute Type Description
input UpdateServiceAccessKeyInput! Mandatory. Provides input data to the mutation.
UpdateServiceAccessKeyInput type
Attribute Type Description
appId ID! Mandatory. The identifier of the app where the service access key is applicable.
tenantId ID! Mandatory. The identifier of the tenant where the service access key is applicable.
publicKey String! Mandatory. The public key of the service access key.
active Boolean Optional, for future use.
description String Optional. Provides a description for the generated key.
scope Scope Optional. Defines the extent of permissions available to the bearer of the key. For syntax details, see Restrict access to services.

Result

See the ServiceAccessKey type.

updateTenant

Arguments

Attribute Type Description
id ID! Mandatory. Specifies the ID of the tenant to be updated.
input UpdateTenantInput! Mandatory. Provides input data to the mutation.
UpdateTenantInput type
Attribute Type Description
name String Optional. Specifies the new tenant name.
active Boolean Optional, for future use. Activates or deactivates the tenant.
onlineBankingEnabled Boolean Optional. Set this value to true to enable online banking for this tenant. Set it to false to disable online banking.
onlineBankingBalanceInquiryMonthlyQuota Float Optional. Sets the number of monthly online banking balance inquiries allowed for this tenant. A null or zero value means unlimited balance inquiries are allowed.
onlineBankingTransactionsInquiryMonthlyQuota Float Optional. Sets the number of monthly online banking transaction inquiries allowed for this tenant. A null or zero value means unlimited transaction inquiries are allowed.

Result

See the Tenant type.

verifyDomainIdentity

Initiates a domain identity verification process at application level. See Verify a domain identity at application level for more information.

Arguments

Attribute Type Description
appId ID! Mandatory. The identifier of the app to which the domain identity is being added.
domain Domain! Mandatory. The Internet domain to be verified, for example example.org.

Result

See the DomainIdentity type.

verifyEmailIdentity

Initiates an email identity verification process at application level. See Verify an email identity at application level for more information.

Arguments

Attribute Type Description
appId ID! Mandatory. The identifier of the app to which the email identity is being added.
address EmailAddress! Mandatory. The email address to be verified.

Result

See the EmailIdentity.

Read more

Conventions Authorization Service