Resources API Request and Response

Authentication

The Resources API requires authentication for all requests. Three authentication types are supported. For general information about each authentication type, please see the Authentication section of the API documentation.

Authentication type	Authentication headers	Chain resolution	Availability
Admin	X-Spaaza-Session-User-ID X-Spaaza-Session-Key	X-Spaaza-Chain-ID header	All resources and all operations, subject to the admin user's permissions and access levels
Privileged	Authorization: Bearer {access token ID}:{access token secret}	X-Spaaza-Chain-ID header	All resources and operations except AccessToken and ServiceClient, which are admin-only
End-user	X-Spaaza-Session-User-ID X-Spaaza-Session-Key	X-Spaaza-MyPrice-App-Hostname header	GET only, and only on the resources which are available to end-users

Admin authentication

Admin authentication uses the session credentials of an admin user, together with the X-Spaaza-Chain-ID header. Permissions are checked against the admin user's role for the chain, including the read, write, delete and super-user access levels required by individual resources and properties.

Privileged authentication

Privileged authentication allows a trusted service client to use the Resources API with a bearer access token instead of an admin session:

curl -X GET "https://{API hostname}/resources/{plural resource name}" \
  -H "Authorization: Bearer {access token ID}:{access token secret}" \
  -H "X-Spaaza-Chain-ID: {chain_id}" \
  -H "X-Spaaza-API-version: 1.6.1"

The following applies to privileged requests:

• The access token must have the chain scope for the chain given in the X-Spaaza-Chain-ID header. The chain scope is equivalent to full admin access to that chain, so property-level write permissions are not applied separately.
• GET requests on the Business resource additionally accept the narrower read_businesses scope, matching the scope used by the get-businesses endpoint.
• The AccessToken and ServiceClient resources are not available with privileged authentication: access tokens cannot be used to manage other access tokens or service clients. Requests to those resources return resource_not_found (544).
• Because no admin user is involved, the last_updated_by property is not set by privileged writes.
• Delegation with the X-Spaaza-On-Behalf-Of header is not supported by the Resources API.

End-user authentication

End-user (shopper) authentication allows a customer to retrieve their own data and public chain data through the Resources API, using the session credentials returned by the login endpoint:

curl -X GET "https://{API hostname}/resources/vouchers" \
  -H "X-Spaaza-Session-User-ID: {end-user ID}" \
  -H "X-Spaaza-Session-Key: {session key}" \
  -H "X-Spaaza-MyPrice-App-Hostname: {app hostname}" \
  -H "X-Spaaza-API-version: 1.6.1"

The following applies to end-user requests:

• The chain is derived from the app identified by the X-Spaaza-MyPrice-App-Hostname header, which is required. The X-Spaaza-Chain-ID header is ignored. An end-user session can only be used with an app belonging to the same chain as the user.
• Only GET operations are available, and only on the resources listed in Availability by authentication type. Any other resource or method returns resource_not_found (544) rather than a permission error, so that the existence of resources is not disclosed.
• The GET /resources/schema endpoint is not available to end-users.
• Resources which belong to a user, such as vouchers, are restricted to the objects belonging to the authenticated user.
• Some properties which are only relevant to administration are omitted from end-user responses. The properties concerned are listed on each resource page.
• Filtering, sorting, pagination, text search, geospatial search and recursion levels all behave in the same way as for admin requests.

Availability by authentication type

Resource	Admin	Privileged	End-user
AccessToken	All operations	Not available	Not available
AllowedIpRange	All operations	All operations	Not available
Business	All operations	All operations (GET also accepts read_businesses scope)	GET only
Campaign	Change log only	Change log only	Not available
Chain	GET, PUT and PATCH	GET, PUT and PATCH	Not available
Content Page	All operations	All operations	GET only
ServiceClient	All operations	Not available	Not available
Voucher	All operations	All operations	GET only, own vouchers only

Required Headers

All requests to the Resources API must include the following headers:

Header	Description	Required	Example
X-Spaaza-API-version	API version (minimum 1.6.1)	Yes	1.6.1
X-Spaaza-Chain-ID	Numeric Chain ID for the request	For admin and privileged requests	1743
X-Spaaza-MyPrice-App-Hostname	Hostname of the app the end-user is affiliated with	For end-user requests	{app hostname}
X-Spaaza-Session-User-ID	User ID for authentication	For admin and end-user requests	{your user ID}
X-Spaaza-Session-Key	Session key for authentication	For admin and end-user requests	{your key}
Authorization	Bearer {access token ID}:{access token secret}	For privileged requests	Bearer {id}:{secret}
X-Spaaza-Response-Recursion-Level	Response detail level (0-4, default 3)	Optional	3
Content-Type	Content type for POST/PATCH/PUT requests	For POST/PATCH/PUT	application/json

Responses

Resources API endpoints return payloads in JSON format as follows:

• Single Resource Retrieval: Returns a JSON object representing the resource in accordance with the OpenAPI specification of the resource.
• Multiple Resource Retrieval: Returns a JSON object containing an array of resources along with pagination metadata.

For more detailed information about API response formats, status codes, and data structures, please see the Responses section of the API documentation.

Datetime format

All date-time fields in Resources API responses (properties documented with type: date-time, such as created_date, last_modified_date, expiry_date, redeemed_date, db_redeemed_date and locked_until) are formatted according to the API version supplied in the X-Spaaza-API-version header:

• API version 1.6.8 and above: date-time fields are returned in RFC 3339 format (a profile of ISO 8601), normalised to UTC — for example 2026-07-07T15:30:23+00:00. The offset is always +00:00 regardless of any timezone supplied when the value was set, so the format is consistent between the immediate response to a POST or PATCH and later GET responses.
• API versions 1.6.1 to 1.6.7: date-time fields are returned in the legacy Y-m-d H:i:s format, without a timezone indicator — for example 2026-07-07 15:30:23.

Date-time values supplied in request bodies (for example expiry_date when creating or updating a voucher) are accepted in either format.

The sample responses throughout this documentation use the RFC 3339 format returned by API version 1.6.8 and above. See the versioning page for more details.

Response Recursion Levels

The Resources API supports configurable response detail levels through the X-Spaaza-Response-Recursion-Level header. This controls how much detail is included in API responses, particularly for nested objects and relationships.

Recursion Level Values

• Level 0: Minimal response with only basic identifiers
• Level 1: Basic properties without nested objects
• Level 2: Includes some nested object properties
• Level 3: Default level with comprehensive property details
• Level 4: Maximum detail including all available properties

Usage

Include the X-Spaaza-Response-Recursion-Level header in your requests to specify the desired detail level:

curl -X GET https://{API hostname}/resources/{resource name}/{id} \
  -H "X-Spaaza-Response-Recursion-Level: 2" \
  # ... other headers

Note that, in the case of nested resources, the recursion level applies recursively to related resources as well and the remaining recursion level value is "carried" down the object tree. For example, if you request recursion level 3 for a resource, Resource 1, and a nested resource in Resource 1 has a recursion level of 2, then that nested resource will be returned with recursion level of (3 - 2 = 1).

If not specified, the default recursion level of 3 is used.

Versioning

For information about API versioning and version compatibility, please see the Versioning section of the API documentation.

Possible Error Responses

The following error codes are specific to or commonly returned by the Resources API. Errors are listed in ascending order by code number.

Resources API-specific errors

These errors are unique to the Resources API:

Code	Name	HTTP Status	Description
533	missing_parameter	400	A required parameter or header is missing (for example a missing X-Spaaza-Chain-ID header).
534	invalid_parameter	400	A parameter is invalid, such as an incorrect Content-Type, an invalid JSON body, or an unrecognised filter.
539	unknown_resource_type	400	The resource type in the URL path is not recognised.
540	resource_type_not_properly_configured	400	The requested resource type is not properly configured on the server.
541	resource_already_exists	400	A POST request attempted to create a resource that already exists (matched by identifier).
542	schema_error	400	An error occurred while generating or processing the OpenAPI schema.
543	parameter_validation_error	400	One or more parameters failed validation against the OpenAPI schema, or pagination/sort values are out of range.
544	resource_not_found	404	The requested resource was not found, or the authentication used is not permitted to access it. This is also returned when a resource or operation is not available for the authentication type used, for example a privileged request for an access token or any write request from an end-user.
545	invalid_endpoint	400	The endpoint path or method is invalid (for example, the API version is below 1.6.1 or the HTTP method is not supported for this path).

General errors applicable to the Resources API

These errors are shared across the Spaaza API and may also be returned by the Resources API:

Code	Name	HTTP Status	Description
6	no_valid_session	401	Authentication is missing or the session is not valid.
68	permission_denied_or_non_existent	403	The authenticated user does not have sufficient permissions for the requested chain or resource.
408	saving_object_error	400	An error occurred while saving the resource. The request may contain data that cannot be persisted.
419	parameter_invalid	400	A parameter value is in an incorrect format (for example, text search or geospatial parameters).
424	access_denied	403	Access to the requested chain or resource is denied for this user.
462	parameter_mismatch	400	Identifier parameters in a PATCH or PUT request resolve to a different resource than the one being updated.

For a complete list of all error codes across the Spaaza API, please see the Error and Warning Codes page.