AccessToken Resource

The AccessToken resource represents a bearer access token issued to a ServiceClient for privileged API authentication. Tokens use a UUID primary key and the plaintext secret is returned only once at creation time — after that only the bcrypt hash is stored.

Contents

• Introduction
• Available Paths
• Properties
• Sample AccessToken JSON (creation response)
• Sample AccessToken JSON (subsequent retrieval)

Introduction

An AccessToken in Spaaza represents a bearer token used for privileged API authentication. Key aspects include:

• UUID-based identifier (not auto-incrementing integer) used in Bearer authentication headers
• Token secret revealed only once at creation time — cannot be retrieved again
• Bearer authentication format: Bearer {id}:{token_secret}
• Scope string controlling what chain/entity the token can access (immutable after creation)
• Active/inactive state to control authentication capability without deletion
• Association with a parent ServiceClient (chain is resolved through this relationship)
• Soft-delete support preserving the token for audit purposes
• Full audit trail with last_updated_by, created_date, and last_modified_date tracking

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

Available Paths

Single Resource Operations

• GET /resources/access_token/{uuid} - Retrieve an access token by UUID path segment
• GET /resources/access_token?id={value} - Retrieve an access token by ID query parameter
• POST /resources/access_token - Create a new access token
• PUT /resources/access_token/{uuid} - Update an access token by UUID
• PATCH /resources/access_token/{uuid} - Partially update an access token by UUID
• DELETE /resources/access_token/{uuid} - Soft-delete an access token by UUID

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/access_tokens - Retrieve a list of access tokens with optional filtering and pagination

Properties

The AccessToken resource includes the following properties, listed alphabetically:

Name	Description	Standard Attributes(details)	Spaaza Vendor Attributes(details)
active	Whether this access token is active and can be used for authentication	type: boolean	recursionLevel: 1 filter-property: true operations: ["put", "patch"]
created_date	Timestamp when this access token was created	type: date-time readOnly: true	recursionLevel: 2 immutable: true sort-by-property: true
deleted	Whether this access token has been soft-deleted; deleted tokens cannot be used for authentication	type: boolean readOnly: true	recursionLevel: 1
id	UUID identifier for this access token, used in Bearer authentication headers	type: string format: uuid readOnly: true	recursionLevel: 0 identifier: true filter-property: true immutable: true operations: ["get", "put", "patch", "delete"]
last_modified_date	Timestamp when this access token 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 access token	type: object readOnly: true nullable: true	recursionLevel: 2
scope	Scope string controlling what the token can access (e.g. chain:1750). Immutable after creation.	type: string	recursionLevel: 1 immutable: true filter-property: true operations: ["post"]
service_client	The service client that owns this access token	type: object nullable: false	recursionLevel: 2 filter-property: true operations: ["post", "put", "patch"]
token_secret	The plaintext token secret. ONLY visible once in the creation response — cannot be retrieved again. Use in Bearer authentication headers as Bearer {id}:{token_secret}.	type: string readOnly: true nullable: true	recursionLevel: 1

Property Notes

• Identifier Properties: The id property (UUID) is used as the identifier parameter for retrieving, updating, or deleting access tokens.
• Required Fields: The service_client and scope properties are required when creating new access tokens (POST). Pass service_client as {"service_client": {"id": N}} where N is the service client's numeric ID.
• Token Secret Security: The token_secret field is only present in the response to a POST (creation) request. It cannot be retrieved again after creation. Store it securely immediately after creation.
• Bearer Authentication: Use the token in API requests with the header Authorization: Bearer {id}:{token_secret}.
• Chain Resolution: Access tokens do not have a direct chain property. The chain is resolved through the parent service client relationship (AccessToken → ServiceClient → Chain).
• Filter Properties: Properties marked with filter-property: true can be used to filter results when retrieving multiple access tokens. Filter by service_client using the service client's numeric ID.
• Sortable Properties: Properties marked with sort-by-property: true can be used with the sort_by query parameter when retrieving multiple access tokens. 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 access token.
• Soft-Delete: Deleting an access token sets deleted to true. The token is preserved for audit purposes but can no longer be used for authentication.
• Scope Format: The scope string typically follows the format chain:{chain_id} and is immutable after creation.
• Recursion Levels: The recursionLevel attribute controls at which API response detail levels each property is included.

Sample AccessToken JSON (creation response)

Here is an example of an AccessToken resource as returned by the API when first created. Note the token_secret field which is only visible in this response:

{
  "active": true,
  "created_date": "2026-06-20T10:00:00+00:00",
  "deleted": false,
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "last_modified_date": "2026-06-20T10:00:00+00:00",
  "last_updated_by": {
    "id": 987
  },
  "scope": "chain:1743",
  "service_client": {
    "id": 15,
    "name": "Example Shopify Integration"
  },
  "token_secret": "xK9mN2pQ7rS4tV6wY8zA1bC3dE5fG7hJ9kL0mN2pQ7rS4tV6wY8zA"
}

Important: The token_secret value shown above is only available in the creation response. Store it securely — it cannot be retrieved again.

Sample AccessToken JSON (subsequent retrieval)

Here is an example of an AccessToken resource as returned by subsequent GET requests. Note that token_secret is absent:

{
  "active": true,
  "created_date": "2026-06-20T10:00:00+00:00",
  "deleted": false,
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "last_modified_date": "2026-06-20T14:30:00+00:00",
  "last_updated_by": {
    "id": 987
  },
  "scope": "chain:1743",
  "service_client": {
    "id": 15,
    "name": "Example Shopify Integration"
  }
}

This example shows a typical AccessToken resource after creation. The actual properties returned depend on the requested recursion level.