Authentication
Use scoped API tokens, user sessions, or publishable storefront keys.
Choose credentials based on who is making the request and which API they need.
Credential types
| Type | Intended use | Header |
|---|---|---|
Scoped API token (sfk_…) | Server-side integrations and machine access | Authorization: Bearer sfk_… |
| Session JWT | An authenticated user acting within their role | Authorization: Bearer <JWT> |
Publishable key (pk_sf_…) | Public shop catalog and checkout creation | Authorization: Bearer pk_sf_… |
Keep session JWTs and secret API tokens out of public storefront code. A publishable key identifies a shop and is designed for the storefront API.
Scoped API tokens
An administrator creates tokens in the shop admin or through POST /api/admin/api-tokens using a session JWT. Token management cannot be called using another API token.
{
"name": "Catalog integration",
"scopes": ["catalog:read"],
"expires_in_days": 90,
"environment": "test"
}
The response includes token metadata in token and the one-time secret in plaintext. Expiry can be set from 1 to 365 days. The environment label defaults to live; choose the correct API host and credentials for the environment you actually want to access.
Read scopes
| Scope | Resource area |
|---|---|
catalog:read | Products, categories, brands, suppliers, and selected channel data |
orders:read | Orders, selected order audit data, fulfillments, and returns |
inventory:read | Warehouses, locations, stock, and purchase orders |
customers:read | Customer records and selected order and audit data |
finance:read | Selected vendor and affiliate data |
The policy also defines catalog:write and inventory:write. These have explicit method/path allowlists and additional validation. Deletion uses the approval flow. There is no general-purpose orders:write, finance:write, or wildcard scope.
Effective access depends on both the token scopes and the creator's current role. The scopes endpoint currently advertises the read scopes; consult the deployed policy before setting up write integrations.
User login
curl "$SELLFORGE_ADMIN_URL/api/auth/login" \
-H 'Content-Type: application/json' \
-d '{"email":"[email protected]","password":"your-password"}'
Without two-factor authentication, the response includes token and user. The user object uses id, email, role, display_name, must_change_password, and must_setup_2fa.
Two-factor authentication
When 2FA is enabled, login returns an intermediate response:
{
"twofa_required": true,
"twofa_token": "<short-lived-stage-one-token>"
}
Complete the second step through POST /api/auth/2fa/verify. The stage-one token is valid for five minutes and is not a full session JWT.
{
"twofa_token": "<short-lived-stage-one-token>",
"code": "123456"
}
To use a backup code, send that value in code and include is_backup_code: true. A successful verification returns the full token and user.
Honor must_change_password and must_setup_2fa in login responses before attempting protected operations. Authentication endpoints apply a limit of 10 requests per minute per IP.
Storefront authentication
curl "$SELLFORGE_STORE_URL/api/store/products" \
-H "Authorization: Bearer $SELLFORGE_PUBLIC_KEY"
The publishable key selects the tenant. Storefront origin restrictions and sales-channel resolution are applied separately. A publishable key does not grant administrative access.
Read Storefront for more details.
Found something unclear? Let us know