Skip to main content

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​

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

Authentication​

This resource is only available with admin authentication. It is not available with privileged (bearer access token) authentication — an access token cannot be used to manage access tokens — and it is not available to end-users. Requests using either of those authentication types return resource_not_found (544).

Properties​

The AccessToken resource includes the following properties, listed alphabetically:

NameDescriptionStandard Attributes(details)Spaaza Vendor Attributes(details)
activeWhether this access token is active and can be used for authenticationtype: booleanrecursionLevel: 1
filter-property: true
operations: ["put", "patch"]
created_dateTimestamp when this access token was createdtype: date-time
readOnly: true		recursionLevel: 2
immutable: true
sort-by-property: true
deletedWhether this access token has been soft-deleted; deleted tokens cannot be used for authenticationtype: boolean
readOnly: true		recursionLevel: 1
idUUID identifier for this access token, used in Bearer authentication headerstype: string
format: uuid
readOnly: true		recursionLevel: 0
identifier: true
filter-property: true
immutable: true
operations: ["get", "put", "patch", "delete"]
last_modified_dateTimestamp when this access token was last modifiedtype: date-time
readOnly: true		recursionLevel: 2
immutable: true
sort-by-property: true
last_updated_byAdmin user who last created, updated or deleted this access tokentype: object
readOnly: true
nullable: true		recursionLevel: 2
scopeScope string controlling what the token can access (e.g. chain:1750). Immutable after creation. See Scope for the accepted values.type: stringrecursionLevel: 1
immutable: true
filter-property: true
operations: ["post"]
service_clientThe service client that owns this access tokentype: object
nullable: false		recursionLevel: 2
filter-property: true
operations: ["post", "put", "patch"]
token_secretThe 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.
  • Revocation: A request made with an inactive or deleted access token, or with an access token of a disabled or deleted service client, is rejected with the error access_token_invalid (code 266). A revocation made through the Resources API can take up to one hour to take effect. See access token revocation.
  • 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.

Scope​

The scope property is a comma-separated list of key:value fields that determines what a token can access, and it cannot be changed after creation. A token created through POST /resources/access_token can only be given scopes bound to the chain in the X-Spaaza-Chain-ID header of the request:

ScopeGrants
chain:{chain_id}Full privileged access to the chain, equivalent to admin access. This is the scope used by most integrations.
read_businesses:{chain_id}Read-only access to the businesses (stores) of the chain, through GET requests on the Business resource and the get-businesses endpoint.

{chain_id} must be the numeric ID of the chain given in X-Spaaza-Chain-ID. A POST request whose scope contains any other field — a chain or read_businesses scope for a different chain, or any other scope key — is rejected with the error access_denied (code 424) and no token is created. Scopes that grant access across chains are provisioned by Spaaza and cannot be created through this resource; contact Spaaza if your integration needs one.

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.