API Tokens¶

Overview¶

API Tokens provide secure authentication for external applications and integrations to access your Trinavo Shop API. This feature allows you to generate, manage, and revoke API tokens with granular permission control.

Purpose¶

API Authentication: Securely authenticate external applications and services
Integration Support: Enable third-party integrations with your store
Granular Permissions: Control what each token can access with ability-based permissions
User-Specific Tokens: Associate tokens with specific users for accountability
Token Management: Create, view, and revoke tokens as needed
Security Control: Monitor token usage and revoke compromised tokens immediately

Accessing API Tokens¶

Navigate to: User Management > API Tokens from the sidebar

The API Tokens menu item displays a badge showing the total number of active tokens in the system. The badge color indicates status:

Green: One or more tokens exist
Gray: No tokens exist

List View¶

API Tokens List

The list view displays all API tokens in the system. If no tokens exist, you'll see a "No API Tokens" message.

Table Columns¶

User: The user account this token belongs to (searchable, sortable, shows email as description)
Token Name: Descriptive name for the token (searchable, sortable, displayed in bold)
Token: The actual token value (always displayed as •••••••••••••••• for security)
Important: Token value is only visible ONCE when first created
Cannot be copied from the list view
If lost, must revoke and create new token
Abilities: Permissions granted to this token (displayed as green badges, comma-separated)
Last Used: When the token was last used to access the API (datetime with relative time like "2 hours ago", sortable)
Shows "Never" if token has never been used
Created: When the token was created (datetime with relative time, sortable, always visible)
Expires: Token expiration date (datetime, hidden by default, can be toggled visible)
Shows "Never" if no expiration set
Currently, tokens don't expire by default

Default Sorting¶

Tokens are sorted by Created At in descending order (newest tokens first).

Search Functionality¶

Use the search box to find tokens by:

User name
User email
Token name

Filters¶

Click the Filter button to access these filtering options:

User Filter¶

Filter tokens by specific user
Searchable dropdown showing up to 100 users
Shows only tokens belonging to the selected user

Used Tokens Only¶

Toggle to show only tokens that have been used at least once
Filters by tokens where last_used_at is not null
Useful for auditing active integrations

Never Used¶

Toggle to show only tokens that have never been used
Filters by tokens where last_used_at is null
Useful for identifying unused/forgotten tokens

Row Actions¶

Each token row has the following action buttons:

Revoke¶

Function: Permanently deletes the token
Warning: This action cannot be undone
Effect: Token becomes immediately invalid and cannot be used for API requests
Use Case: Revoke compromised tokens, remove access for terminated integrations

View¶

Function: Opens a modal window with detailed token information
Use Case: Review token configuration without editing

Bulk Actions¶

Select multiple tokens using the checkboxes, then choose from:

Revoke Selected¶

Label: "Revoke Selected"
Function: Delete multiple tokens at once
Warning: This action cannot be undone
Confirmation: Shows confirmation dialog before deletion
Use Case: Clean up multiple unused tokens, revoke access for multiple integrations

Creating API Tokens¶

Create API Token

Create new API tokens to enable external applications and services to access your store's API.

Token Details¶

User Required¶

Type: Searchable dropdown
Function: Select which user account this token belongs to
Search: Search by user name or email
Display Format: "User Name (email@example.com)"
Limit: Shows up to 50 results per search
Validation: Required field
Purpose: Associates the token with a user for accountability and permissions

Important: The token will inherit any user-level restrictions. Choose the appropriate user account based on what the integration needs to access.

Token Name Required¶

Type: Text input
Function: Descriptive name to identify this token
Validation: Required, maximum 255 characters
Placeholder: "My API Token"
Helper Text: "A descriptive name for this token"
Examples:
"Mobile App Integration"
"Shopify Sync"
"Analytics Dashboard"
"Warehouse Management System"
"Marketing Automation Tool"

Best Practice: Use clear, descriptive names that indicate the integration purpose and environment (e.g., "Shopify Sync - Production" vs "Shopify Sync - Staging").

Abilities / Permissions Required¶

Type: Multi-select dropdown
Function: Define what operations this token can perform
Validation: Required, at least one ability must be selected
Default: Full Access (*)
Helper Text: "Choose what this token can do. '⭐ Full Access' means full access to all endpoints."
Hint: "Select one or more permissions"

Available Permissions:

Full Access¶

⭐ Full Access (All Permissions) (*)
Grants complete access to all API endpoints
Includes all read, write, and delete operations
Use with caution - only for trusted integrations
Cannot be combined with other permissions (selecting this overrides all others)

Categories Permissions¶

📁 Categories: Read Only (GET) (categories:read)
View category listings and details
Cannot create, update, or delete categories
Safe for analytics and reporting tools
📝 Categories: Create & Update (POST, PUT, PATCH) (categories:write)
Create new categories
Update existing categories
Does NOT include delete permission
Requires categories:read for most practical use cases
🗑️ Categories: Delete (DELETE) (categories:delete)
Delete categories
High-risk permission - use carefully
Consider implications for products in deleted categories

Items (Products) Permissions¶

👁️ Items: Read Only (GET) (items:read)
View product listings and details
Access inventory information
Safe for display integrations (mobile apps, POS systems)
✏️ Items: Create & Update (POST, PUT, PATCH) (items:write)
Create new products
Update product details, pricing, inventory
Does NOT include delete permission
Common for inventory management integrations
🗑️ Items: Delete (DELETE) (items:delete)
Delete products
High-risk permission
May affect orders and other references

Orders Permissions¶

📋 Orders: Read Only (GET) (orders:read)
View order listings and details
Access customer order history
Common for reporting and analytics integrations
📝 Orders: Create (POST) (orders:write)
Create new orders
Useful for POS systems and external sales channels
Note: Typically cannot update or delete orders for security/audit reasons

Form Actions¶

Create¶

Creates the token and displays the token value ONE TIME ONLY
Shows success notification with the generated token
Critical: Copy and save the token immediately - it cannot be retrieved again
Returns to the list view
Token becomes active immediately

Cancel¶

Discards the form and returns to the list view
No token is created

Important Security Notes¶

Token Value Security¶

The token value is shown ONLY ONCE when first created.

After creation, you'll see a notification or modal with the full token value
Copy and save it immediately - you cannot retrieve it again
If lost, you must revoke the token and create a new one
In the list view, tokens are always masked as ••••••••••••••••
This is a critical security feature to prevent token theft

Token Storage Best Practices¶

Where to Store Tokens:

✅ Environment variables in your application (.env file)
✅ Secure secret management systems (AWS Secrets Manager, HashiCorp Vault)
✅ Encrypted configuration files
❌ NEVER commit tokens to version control
❌ NEVER store in plain text files
❌ NEVER share via email or chat

Token Compromise Response¶

If a token is compromised:

Immediately revoke the compromised token
Create a new token with different credentials
Update your integration with the new token
Review API access logs for unauthorized usage
Consider revoking all tokens for the affected user if unsure

How API Tokens Work¶

Authentication Flow¶

Create Token: Generate a token with specific permissions
Store Securely: Save the token in your application's secure storage
API Request: Include token in request header: Authorization: Bearer {your-token}
Permission Check: API validates token and checks if requested action is allowed
Response: API processes request and returns response

Permission Model¶

Tokens use an ability-based permission system:

Wildcard (*): Grants all permissions
Namespace Permissions: Permissions are grouped by resource (categories, items, orders)
Operation Types:
read: GET requests (view data)
write: POST, PUT, PATCH requests (create/update data)
delete: DELETE requests (remove data)
Cumulative: Can select multiple permissions for mixed access
Checked on Each Request: Every API request checks token abilities

Example Permission Combinations:

Read-Only Integration (Analytics Dashboard):
categories:read
items:read
orders:read
Inventory Management:
items:read
items:write
Full Product Management:
items:read
items:write
items:delete
categories:read
categories:write

Token Usage Tracking¶

The system tracks when each token is used:

Last Used At: Updated every time the token successfully authenticates
Never Used: Indicates token has been created but not used yet
Use this data to identify:
Active vs. inactive integrations
Potentially forgotten tokens
Integration health

Use Cases¶

Example 1: Mobile App Integration¶

Token Name: "iOS Mobile App - Production"
User: App Service Account
Abilities:
items:read (browse products)
categories:read (browse categories)
orders:write (create orders)
orders:read (view order history)
Purpose: Allow mobile app to display products and place orders

Example 2: Inventory Sync System¶

Token Name: "Warehouse Management System - Sync"
User: Inventory Manager Account
Abilities:
items:read (check current inventory)
items:write (update stock levels)
Purpose: Keep inventory synchronized between systems

Example 3: Analytics Platform¶

Token Name: "Business Intelligence Dashboard"
User: Analytics Service Account
Abilities:
orders:read (analyze sales data)
items:read (product performance)
categories:read (category analysis)
Purpose: Read-only access for reporting and analytics

Example 4: External Sales Channel¶

Token Name: "Shopify Integration"
User: Integration Service Account
Abilities:
⭐ Full Access (*) OR specific subset based on trust level
Purpose: Sync products, orders, and inventory between platforms

Example 5: Development/Testing¶

Token Name: "Development Environment - Testing"
User: Developer Account
Abilities: * (full access for testing)
Purpose: Test API functionality during development
Note: Revoke after development is complete

Users - API token owners
Roles - Permission management