Authentication Guide

Learn how to authenticate with the Stockaj API and manage access tokens.

Token Types

Stockaj uses Laravel Sanctum tokens. There are two token contexts:

Type	Created By	Use Case
User Token	User via profile/API	Full API access scoped to user's permissions
Instance Token	Workspace admin via Settings	Workspace-level API access with fine-grained abilities

For most integrations, Instance Tokens are recommended — they're tied to a workspace and have explicit ability control.

Creating Tokens

Via the Web UI

1. Go to Settings → API Tokens.
2. Click + New Token.
3. Name your token (e.g., warehouse-scanner-prod).
4. Select abilities.
5. Click Create and immediately copy the token.

warning

The token is shown only once at creation time. If you lose it, you'll need to create a new one.

Token Naming Conventions

Use descriptive names that indicate the token's purpose and environment:

warehouse-scanner-prod
inventory-sync-staging
mobile-app-v2
ci-testing

Using Tokens

HTTP Header

Include the token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Full Example

curl -X GET "https://app.stockaj.com/api/v2/items" \
  -H "Authorization: Bearer 1|a1b2c3d4e5f6g7h8..." \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

JavaScript

const response = await fetch('https://app.stockaj.com/api/v2/items', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json',
  },
});
const data = await response.json();

Python

import requests

response = requests.get(
    'https://app.stockaj.com/api/v2/items',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Accept': 'application/json',
    },
)
data = response.json()

PHP

$response = Http::withToken('YOUR_API_TOKEN')
    ->acceptJson()
    ->get('https://app.stockaj.com/api/v2/items');

$data = $response->json();

Token Abilities

Control what each token can do with fine-grained abilities:

Read-Only Abilities

Ability	Resources
items:read	Items, variants, types, tags
renters:read	Renters
rents:read	Rentals
webhooks:read	Webhooks
notifications:read	Notifications
instance:read	Workspace settings

Write Abilities

Ability	Resources
items:create	Create items, variants, types, tags
items:update	Update items, variants, types, tags
items:delete	Delete/restore items, variants, types, tags
renters:create	Create renters
renters:update	Update renters
renters:delete	Delete/restore renters
rents:create	Create rentals
rents:update	Update rentals
rents:delete	Delete rentals

Special Abilities

Ability	Purpose
kiosk:scan	Use kiosk scan and search endpoints
webhooks:manage	Create/update/delete webhooks
notifications:manage	Manage notification state and preferences
instance:manage	Update workspace settings

Security Best Practices

1. Principle of least privilege — Only grant the abilities your integration actually needs.
2. Separate tokens per integration — Use different tokens for different services so you can revoke them independently.
3. Rotate tokens regularly — Periodically create new tokens and retire old ones.
4. Never commit tokens — Use environment variables or secret managers.
5. Use HTTPS only — Tokens are sent in headers; HTTPS prevents interception.
6. Monitor usage — Review API access patterns and revoke unused tokens.

Error Responses

401 Unauthorized

Token is missing, invalid, or expired:

{
  "message": "Unauthenticated."
}

403 Forbidden

Token doesn't have the required ability:

{
  "message": "This action is unauthorized."
}

Resolution: Create a new token with the needed abilities, or update the existing token's permissions.