ServiceClient Resource

The ServiceClient resource represents a registered external API client that authenticates via bearer access tokens for privileged chain-level access in the Spaaza platform. Service clients are used by trusted external parties (such as e-commerce platform extensions or a retailer's own backend system) that need chain-level API access.

Contents

• Introduction
• Available Paths
• Properties
• Sample ServiceClient JSON

Introduction

A ServiceClient in Spaaza represents an external API consumer that authenticates using bearer access tokens rather than user credentials. Key aspects include:

• A human-readable name and optional contact email for identification
• Enabled/disabled state to control authentication capability
• Identity source designation for service clients associated with authentication points (e.g. Shopify, Magento)
• Associated access tokens for bearer authentication
• Full audit trail with last_updated_by, created_date, and last_modified_date tracking
• Soft-delete support with deleted_by tracking

All write operations (POST, PUT, PATCH, DELETE) require super-user admin access.

Available Paths

Single Resource Operations

• GET /resources/service_client/{id} - Retrieve a service client by ID
• GET /resources/service_client?id={value} - Retrieve a service client by ID query parameter
• POST /resources/service_client - Create a new service client
• PUT /resources/service_client/{id} - Update a service client by ID
• PATCH /resources/service_client/{id} - Partially update a service client by ID
• DELETE /resources/service_client/{id} - Soft-delete a service client by ID

Note: For single resource retrieval by identifier parameter, you can use any property marked with identifier: true in the "Spaaza Vendor Attributes" column in the Properties table below.

Multiple Resource Operations

• GET /resources/service_clients - Retrieve a list of service clients with optional filtering and pagination

Properties

The ServiceClient resource includes the following properties, listed alphabetically:

Name	Description	Standard Attributes(details)	Spaaza Vendor Attributes(details)
access_tokens	Access tokens issued under this service client	type: array readOnly: true	recursionLevel: 3
chain	Chain to which this service client belongs	type: object readOnly: true nullable: false	recursionLevel: 2 immutable: true
created_date	Timestamp when this service client was created	type: date-time readOnly: true	recursionLevel: 2 immutable: true sort-by-property: true
deleted	Whether this service client has been soft-deleted	type: boolean readOnly: true	recursionLevel: 1
deleted_by	Admin user who deleted this service client	type: object readOnly: true nullable: true	recursionLevel: 2
email_contact	Contact email address for this service client	type: string format: email maxLength: 256	recursionLevel: 1 operations: ["post", "put", "patch"]
enabled	Whether this service client is enabled. Disabled clients cannot authenticate.	type: boolean	recursionLevel: 1 filter-property: true operations: ["put", "patch"]
id	ServiceClient identifier	type: integer readOnly: true	recursionLevel: 0 identifier: true filter-property: true immutable: true operations: ["get", "put", "patch", "delete"]
is_identity_source	Whether this service client is the identity source for the chain. Should only be true for service clients associated with an authentication point. Only one active service client per chain should have this set to true.	type: boolean	recursionLevel: 1 operations: ["post", "put", "patch"]
last_modified_date	Timestamp when this service client was last modified	type: date-time readOnly: true	recursionLevel: 2 immutable: true sort-by-property: true
last_updated_by	Admin user who last created, updated or deleted this service client	type: object readOnly: true nullable: true	recursionLevel: 2
name	Human-readable name identifying this service client	type: string nullable: false minLength: 1 maxLength: 255	recursionLevel: 1 filter-property: true sort-by-property: true required-in: ["post"] operations: ["post", "put", "patch"]

Property Notes

• Identifier Properties: The id property is used as the identifier parameter for retrieving, updating, or deleting service clients.
• Required Fields: The name property is required when creating new service clients (POST).
• Chain Reference: The chain property refers to the Chain resource. The chain is automatically set from the X-Spaaza-Chain-ID header and cannot be modified.
• Filter Properties: Properties marked with filter-property: true can be used to filter results when retrieving multiple service clients.
• Sortable Properties: Properties marked with sort-by-property: true can be used with the sort_by query parameter when retrieving multiple service clients. See Pagination and Sorting for details.
• Write Access: All write operations (POST, PUT, PATCH, DELETE) require super-user admin access.
• Audit Trail: The last_updated_by property automatically records the admin user who last created, updated, or deleted the service client.
• Access Tokens: The access_tokens array contains AccessToken objects associated with this service client. Tokens are created via the AccessToken resource endpoint, not directly on the ServiceClient.
• Identity Source: Only one active (non-deleted) service client per chain should have is_identity_source set to true. This is used for service clients associated with an authentication point (e.g. Shopify, Magento).
• Soft-Delete: Deleting a service client soft-deletes it and deactivates all its access tokens. The deleted_by property records the admin user who performed the deletion.
• Recursion Levels: The recursionLevel attribute controls at which API response detail levels each property is included.

Sample ServiceClient JSON

Here is an example of a ServiceClient resource as returned by the API:

{
  "access_tokens": [
    {
      "active": true,
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "scope": "chain:1743"
    }
  ],
  "chain": {
    "id": 1743,
    "name": "Example Retail Chain"
  },
  "created_date": "2026-06-01T09:00:00+00:00",
  "deleted": false,
  "deleted_by": null,
  "email_contact": "integrations@example.com",
  "enabled": true,
  "id": 15,
  "is_identity_source": false,
  "last_modified_date": "2026-06-20T14:30:00+00:00",
  "last_updated_by": {
    "id": 987
  },
  "name": "Example Shopify Integration"
}

This example shows a typical ServiceClient resource with chain association, access tokens, and audit information. The actual properties returned depend on the requested recursion level.