Account API

The Account API enables you to manage all SBS entities through API calls, just as you would 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 in the table below, 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.

Access info

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.

Arguments

None.

Result

Account type

CompanyInfo type

Address type

aggregatedUsage

Returns the total usage of SBS services for a particular time interval, grouped by service, usage measurement type (counter), tenant, and application. Unlike the usage query, which returns a per-date breakdown, this query returns a single total for each group. Because the service and type filter attributes are optional, one call can report the whole account’s consumption across every service and counter at once. Querying usage is meaningful only for those services that have usage measurement types (counters). To retrieve the list of services and their available counters, run the usageFilters query.

Arguments

AggregatedUsageFilter type

A counter name is meaningful only within a service, so name the service whenever you name a counter. The call is rejected if you supply a type without a service, and also if you supply a type that is not a counter of the given service.

Result

The result is an object of type AggregatedUsageResult.

AggregatedUsageResult type

AggregatedUsageValue type

Example

query aggregatedUsage($filter:AggregatedUsageFilter!,$nextToken:String,$limit:Int) {
  aggregatedUsage(filter:$filter,nextToken:$nextToken,limit:$limit){
    items {
      service
      type
      value
      app { id name }
      tenant { id name }
    }
    nextToken
  }
}

The following variables return the outbound invoice count of the Romanian e-Factura Service in the production environment:

{
  "filter": {
    "from": "2024-12-25",
    "service": "ro-efactura-api",
    "type": "OUTBOUND_INVOICES",
    "environment": "PRODUCTION"
  }
}

The following variables omit both service and type, and therefore return one total for each combination of service, counter, tenant, and application recorded since the given date:

{
  "filter": {
    "from": "2024-12-25"
  }
}

app

Returns information about the application ID supplied as input argument.

Arguments

Result

The result is an object of type App.

App type

ServiceAccessKey type

Tenant type

ServiceAccessDenial type

GoogleClientSecret type

GoogleClientSecretWeb type

AzureClientSecret type

AzureClientSecretWeb type

CognitoClientSecret type

CognitoClientSecretWeb type

RoAnafClientSecret type

OnlineBankingSettings type

EmailIdentity type

DomainIdentity type

DnsRecord type

DomainIdentitiesFilter type

Webhook type

TenantEntry type

AppEntry type

KeyValue type

Example

query app($id:ID!,$domainIdentitiesFilter:DomainIdentitiesFilter){
  app(id:$id){
    id
    name
    domainIdentities(filter: $domainIdentitiesFilter) { domain status }
    emailSenders
  }
}

{
    "appId": "YOUR_APP_ID"
}

apps

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

Arguments

AppsFilter type

Result

The result is an object of type AppsResult.

AppsResult type

calls

Returns information about the API calls that took place for all SBS services. You can query, for example, how many times a particular query or mutation of a particular service was called within a given time period.

Arguments

CallsFilter type

Result

The result is an object of type CallsResult.

CallsResult type

CallsValue type

portalUser

Returns an SBS Portal user by ID.

Arguments

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

PortalUsersFilter type

Result

The result is an object of type PortalUsersResult.

PortalUsersResult type

PortalUser type

Permission type

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 prefix that identifies the key type. If the private key is at the application level, it begins with app-. If the key is at the tenant level, it begins with ten-.

Arguments

ServiceAccessKeysFilter type

Result

ServiceAccessKeyResult type

serviceAccessRoles

Returns the list of service access roles for the current account.

Arguments

None.

Result

The response is an array of ServiceAccessRole.

ServiceAccessRole type

servicePlans

Returns the service plans defined for the current account. A service plan applies to one combination of tenant, app, and service, and tells the consuming service which tier to apply to that combination. What a tier changes is each service’s own business; the Account API only records which plan applies. Only non-standard plans are recorded, so the result lists exceptions: a combination that the query does not return is on the STANDARD plan.

Arguments

ServicePlansFilter type

Result

The result is an array of objects of type ServicePlan.

ServicePlan type

Example

The following query retrieves every service plan defined for one app:

query servicePlans($filter:ServicePlansFilter) {
  servicePlans(filter:$filter) {
    tenant {
      id
      name
      active
    }
    app {
      id
      name
    }
    service
    plan
  }
}

With variables:

{
  "filter": {
    "appId": "YOUR_APP_ID"
  }
}

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

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"
}

serviceSchemaFields

Returns the queries or the mutations published by the schema of a service, each with the description that the schema provides for it.

One use for the result is writing a scope string. A scope names the query or mutation it applies to, and this query supplies those names. For example, email-api:mutation:unsuppressAddress targets a single mutation of the Email Service.

Arguments

Result

The result is an array of objects of type ServiceSchemaField, one for each query or mutation of the requested operation type. Deprecated queries and mutations are excluded from the result. If the schema of the requested service cannot be read, the result is an empty array.

ServiceSchemaField type

Example

The following query retrieves the mutations of the Organizations Service:

query serviceSchemaFields($service:ServiceCode!, $operationType:OperationType!) {
  serviceSchemaFields(service:$service, operationType:$operationType) {
    name
    description
  }
}

With variables:

{
  "service": "organizations-api",
  "operationType": "mutation"
}

The result:

{
  "data": {
    "serviceSchemaFields": [
      {
        "name": "createOrganization",
        "description": "Creates an organization. Once an organization is created it can be referenced multiple times by different declarations."
      },
      {
        "name": "updateOrganization",
        "description": "Updates an organization."
      },
      {
        "name": "deleteOrganization",
        "description": "Delete an organization. Possible only if the organization is not referenced by any declaration."
      }
    ]
  }
}

tenant

Returns the tenant matching the ID supplied as input argument.

Arguments

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

TenantsFilter type

Result

The result is an array of objects of type TenantsResult.

TenantsResult type

usage

Returns information about usage of SBS services. Querying usage is meaningful only for those services that have usage measurement types (counters). To retrieve the list of services and their available counters, run the usageFilters query.

Arguments

UsageMeasurementFilter type

Result

The result is an object of type UsageMeasurementResult.

UsageMeasurementResult type

MeasurementValue type

usageFilters

Returns the usage measurement types (or “counters”) available for each service when you run the usage or aggregatedUsage query. It also returns the filters that apply to and are meaningful for the service supplied as input.

Arguments

Result

The result is an array of objects of UsageFilters type.

UsageFilters type

Example

The following call retrieves information for all services (note that no parameters are supplied):

query UsageFilters($service:ServiceCode) {
  usageFilters(service:$service) {
    service
    types
    appId
    tenantId
    environment
  }
}

The following call retrieves information for the Romanian e-Factura Service:

query UsageFilters($service:ServiceCode) {
  usageFilters(service:$service) {
    service
    types
    appId
    tenantId
    environment
  }
}

{
  "service": "ro-efactura-api"
}

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 that was created through the verifyDomainIdentity mutation.

Arguments

Result

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

Example

mutation AddEmailSender($appId:ID!,$address:EmailAddress!) {
  addEmailSender(appId:$appId,address:$address)
}

{
    "appId": "YOUR_APP_ID",
    "address": "jane.doe@example.org"
}

addWebhook

Adds a webhook to an application.

Arguments

WebhookInput type

KeyValueInput type

Result

See the Webhook type.

createApp

Creates a new application.

Arguments

CreateAppInput type

Result

See the App type.

createServiceAccessRole

Creates a new role.

Arguments

CreateServiceAccessRoleInput type

Result

See the ServiceAccessRole type.

createTenant

Creates a new tenant.

Arguments

CreateTenantInput type

Result

See the Tenant type.

deleteAppLevelServiceAccessKey

Deletes an application-level service access key.

Arguments

DeleteAppLevelServiceAccessKeyInput type

Result

See the ServiceAccessKey type.

deleteDomainIdentity

Deletes a domain identity.

Arguments

Result

See the DomainIdentity.

Example

mutation DeleteDomainIdentity($appId:ID!,$domain:Domain!) {
  deleteDomainIdentity(appId:$appId, domain:$domain) {
    domain
    status
    dnsRecords { type name value }
  }
}

{
    "appId": "YOUR_APP_ID",
    "domain": "example.org"
}

deleteEmailIdentity

Deletes an email identity.

Arguments

Result

See the EmailIdentity.

deleteServiceAccessKey

Deletes a service access key.

Arguments

DeleteServiceAccessKeyInput type

Result

See the ServiceAccessKey type.

Example

The code listing below illustrates how to delete a service access key.

mutation DeleteTenantKey($input: DeleteServiceAccessKeyInput!) {
  deleteServiceAccessKey(input: $input){
    publicKey
    # privateKey
    scope
  }
}

{
    "input": {
        "appId": "YOUR_APPLICATION_ID",
        "tenantId": "YOUR_TENANT_ID",
        "publicKey": "YOUR_PUBLIC_KEY",
    }
}

deleteServiceAccessRole

Deletes an existing role.

Arguments

Result

See the ServiceAccessRole type.

deleteWebhook

Arguments

Result

See the Webhook type.

denyServiceAccess

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

Arguments

DenyServiceAccessInput type

Result

See the ServiceAccessDenial type.

generateAppLevelServiceAccessKey

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

Arguments

GenerateAppLevelServiceAccessKeyInput type

Result

See the ServiceAccessKey type.

generateServiceAccessKey

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

Arguments

GenerateServiceAccessKeyInput type

Result

See the ServiceAccessKey type.

Example

The code listing below illustrates how to create a service access key with full access rights to the email-api. This permission is provided by the scope attribute.

mutation generate_sak($appId: ID!, $tenantId: ID!, $active: Boolean, $description: String, $scope: Scope) {
  generateServiceAccessKey(
    input: {appId: $appId, tenantId: $tenantId, active: $active, description: $description, scope: $scope}
  ) {
    privateKey
  }
}

{
  "appId": "YOUR_APPLICATION_ID",
  "tenantId": "YOUR_TENANT_ID",
  "description": "",
  "scope": "email-api:query:* email-api:mutation:*"
}

In the variables, make sure to replace the example values below with the ones you actually require:

• appId - The unique identifier of the application for which you are generating this key. To view all applications and their details, run the apps query first.
• tenantId - The unique identifier of the tenant for which you are generating this key. To view all tenants and their details, run the tenants query first.
• roleId - Optional parameter, not used in this example. If given, this should be the ID of a role created through createServiceAccessRole.
• scope - Optional parameter. If provided, it restricts the scope of the key to specific services only, or to even to specific queries and mutations of a service. In this example, the scope provides full access to all queries and all mutations of the Email Service. For more information about the syntax rules, see Restrict access to services.
• description - An optional text description that will help you easier identify the key later.

The privateKey field in the returned response contains the generated key.

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

InvitePortalUserInput type

Result

PortalUserInvitationType type

PortalUserInvitationPermission type

Example

The following mutation invites a user and grants them read and write access to the Romanian e-Factura Service and the Romanian ANAF Authorizations Service, for one app and tenant:

mutation invitePortalUser($input: InvitePortalUserInput!) {
  invitePortalUser(input: $input) {
    id
    provider
    email
    permissions {
      appId
      tenantId
      scope
    }
  }
}

With variables:

{
  "input": {
    "email": "jane.doe@example.com",
    "permissions": [
      {
        "appId": "YOUR_APP_ID",
        "tenantId": "YOUR_TENANT_ID",
        "scope": "ro-efactura-api:query:* ro-efactura-api:mutation:* ro-anaf-oauth-api:query:* ro-anaf-oauth-api:mutation:*"
      }
    ]
  }
}

To grant the same access across every tenant of the account, set tenantId to *. See Wildcard tenant permissions.

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

RegisterAppSubdomainInput type

Result

AppSubDomain type

removeEmailSender

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

Arguments

Result

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

Example

mutation RemoveEmailSender($appId:ID!,$address:EmailAddress!) {
 removeEmailSender(appId:$appId,address:$address) 
}

{
    "appId": "{{appId}}",
    "address": "jane.doe@example.org"
}

removePortalUser

Deletes a portal user.

Arguments

Result

See the PortalUser type.

Example

mutation removePortalUser($userId: ID!) {
  removePortalUser(userId: $userId) {
    userId
    provider
    email
    name
    createdAt
  }
}

With variables:

{
  "userId": "YOUR_PORTAL_USER_ID"
}

removePortalUserInvitation

Removes a pending SBS Portal user invitation.

Arguments

Result

See the PortalUserInvitation type.

removePortalUserPermission

Removes permissions previously granted to a portal user.

Arguments

PermissionKeyInput type

Result

See the PortalUser type.

Example

The following mutation removes the permission that a portal user holds for one app and tenant combination:

mutation removePortalUserPermission($userId: ID!, $permissionKey: PermissionKeyInput!) {
  removePortalUserPermission(userId: $userId, permissionKey: $permissionKey) {
    userId
    provider
    email
    name
    picture
    createdAt
    permissions {
      appId
      app { name }
      tenantId
      tenant { name }
      scope
      createdAt
    }
  }
}

With variables:

{
  "userId": "YOUR_PORTAL_USER_ID",
  "permissionKey": {
    "appId": "YOUR_APP_ID",
    "tenantId": "YOUR_TENANT_ID"
  }
}

To remove a permission that applies to every tenant of the account, set tenantId to *. See Wildcard tenant permissions.

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

RevokeServiceAccessDenialInput type

Result

See the ServiceAccessDenial type.

setPortalUserPermission

Grants a portal user a permission for an app and tenant combination. If the portal user already holds a permission for that combination, the values you supply replace the existing ones; a scope or roles value you omit is left unchanged.

Arguments

PermissionInput type

Result

See the PortalUser type.

Example

The following mutation grants a portal user access to all queries and mutations of the Email Service and the File Management Service, for one app and tenant:

mutation setPortalUserPermission($userId: ID!, $permission: PermissionInput!) {
  setPortalUserPermission(userId: $userId, permission: $permission) {
    userId
    provider
    email
    name
    picture
    createdAt
    permissions {
      appId
      app { name }
      tenantId
      tenant { name }
      scope
      createdAt
    }
  }
}

With variables:

{
  "userId": "YOUR_PORTAL_USER_ID",
  "permission": {
    "appId": "YOUR_APP_ID",
    "tenantId": "YOUR_TENANT_ID",
    "scope": "email-api:query:* email-api:mutation:* file-management-api:query:* file-management-api:mutation:*"
  }
}

To grant the same access across every tenant of the account, set tenantId to *. The returned permission then carries tenantId * and a tenant of null. See Wildcard tenant permissions.

setServicePlan

Assigns a service plan to a combination of tenant, app, and service. If the combination already has a plan, its plan code is replaced. Because only non-standard plans are recorded, setting the plan to STANDARD returns the combination to the standard plan and has the same effect as unsetServicePlan.

Arguments

ServicePlanInput type

Result

See the ServicePlan type.

Example

The following mutation places one tenant on the limited plan for a given app and service:

mutation setServicePlan($input:ServicePlanInput!) {
  setServicePlan(input:$input) {
    tenant {
      id
      name
    }
    app {
      id
      name
    }
    service
    plan
  }
}

With variables:

{
  "input": {
    "tenantId": "YOUR_TENANT_ID",
    "appId": "YOUR_APP_ID",
    "service": "ro-efactura-api",
    "plan": "LIMITED"
  }
}

unsetServicePlan

Returns a combination of tenant, app, and service to the STANDARD plan by removing the plan recorded for it. Calling the mutation for a combination that has no recorded plan succeeds and changes nothing.

Arguments

ServicePlanKeyInput type

Result

Returns true when the call succeeds.

Example

The following mutation returns a combination to the standard plan:

mutation unsetServicePlan($input:ServicePlanKeyInput!) {
  unsetServicePlan(input:$input)
}

With variables:

{
  "input": {
    "tenantId": "YOUR_TENANT_ID",
    "appId": "YOUR_APP_ID",
    "service": "ro-efactura-api"
  }
}

updateApp

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

Arguments

UpdateAppInput type

GoogleClientSecretInput type

GoogleClientSecretWebInput type

AzureClientSecretInput type

AzureClientSecretWebInput type

CognitoClientSecretInput type

CognitoClientSecretWebInput type

RoAnafClientSecretInput type

This type has the same structure as the RoAnafClientSecret type.

OnlineBankingSettingsInput type

Result

See the App type.

updateCompanyInfo

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

Arguments

CompanyInfoInput type

AddressInput type

Result

See the CompanyInfo type.

updateServiceAccessRole

Updates an existing role.

Arguments

UpdateServiceAccessRoleInput type

Result

See the ServiceAccessRole type.

updateServiceAccessKey

Updates a tenant-level service access key.

Arguments

UpdateServiceAccessKeyInput type

You can update the following fields of a service access key:

• active
• description
• scope
• roleId

The mandatory fields appId, tenantId, and publicKey are used for identifying the key and cannot be updated.

Result

See the ServiceAccessKey type.

Example

The code listing below illustrates how to update a service access key so as to grant to it full access to the Email Service, through the scope attribute.

mutation UpdateKey($input: UpdateServiceAccessKeyInput!) {
    updateServiceAccessKey(input: $input) {
          appId
          app { name }
          tenantId
          tenant { name }
          active
          description
          scope
          role { id name scope createdAt }
          createdAt
    }
}

{
    "input": {
        "appId": "YOUR_APPLICATION_ID",
        "tenantId": "YOUR_TENANT_ID",
        "publicKey": "YOUR_PUBLIC_KEY",
        "scope": "email-api:query:* email-api:mutation:*"
    }
}

In the variables, make sure to replace the example values below with the ones you actually require:

• appId - The unique identifier of the application for which you are generating this key. To view all applications and their details, run the apps query first.
• tenantId - The unique identifier of the tenant for which you are generating this key. To view all tenants and their details, run the tenants query first.
• publicKey - The identifier of the key you are updating (the public key).
• roleId - Optional parameter, not used in this example. If given, this should be the ID of a role created through createServiceAccessRole.
• scope - Optional parameter. If provided, it restricts the scope of the key to specific services only, or to even to specific queries and mutations of a service. In this example, the scope provides full access to all queries and all mutations of the Email Service. For more information about the syntax rules, see Restrict access to services.
• description - An optional text description that will help you easier identify the key later.

updateTenant

Arguments

UpdateTenantInput type

Result

See the Tenant type.

updateWebhook

Arguments

Result

See the Webhook type.

verifyDomainIdentity

Initiates a new domain identity verification process at application level. You can also run this mutation if a previous verification attempt has stalled with status UNVERIFIED. See Verify a domain identity at application level for more information.

Arguments

Result

See the DomainIdentity type.

Example

mutation verifyDomainIdentity($appId:ID!, $domain:Domain!) {
  verifyDomainIdentity(appId:$appId, domain:$domain) {
    domain
    status
    dnsRecords { type name value }
  }
}

{
    "appId": "YOUR_APP_ID",
    "domain": "example.org"
}

verifyEmailIdentity

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

Arguments

Result

See the EmailIdentity type.