Overview
API keys authenticate SDK requests to the S4Kit platform. They follow a Stripe-like model with granular permissions and rate limits.
API keys have a recognizable format:
sk_live_abc123def456ghi789... # Production key
sk_test_abc123def456ghi789... # Test key
sk_ prefix identifies S4Kit keyslive_ or test_ indicates the environment- Random string ensures uniqueness
Creating API Keys
Via Dashboard
- Navigate to API Keys
- Click Create Key
- Configure the key:
| Field | Description |
|---|
| Name | Descriptive name (e.g., “Backend Service”) |
| Description | Optional notes |
| Instances | Which instances the key can access |
| Permissions | Entity-level permissions |
| Rate Limits | Per-minute and per-day limits |
- Click Create
- Copy the key immediately—it won’t be shown again
The full API key is only displayed once. Store it securely.
Permissions
Permission Model
Each API key can have granular permissions:
Instance → Service → Entity → Operations
Operations
| Operation | Description |
|---|
| list | Query multiple entities |
| get | Retrieve single entity |
| create | Create new entities |
| update | Modify existing entities |
| delete | Remove entities |
Example Configuration
production:
API_BUSINESS_PARTNER:
A_BusinessPartner:
- list
- get
A_BusinessPartnerAddress:
- list
- get
dev:
API_BUSINESS_PARTNER:
A_BusinessPartner:
- list
- get
- create
- update
- delete
Wildcard Permissions
Grant access to all entities in a service:
production:
API_BUSINESS_PARTNER:
"*":
- list
- get
Rate Limits
Default Limits
| Limit | Default |
|---|
| Per minute | 60 requests |
| Per day | 10,000 requests |
Custom Limits
Set custom limits per API key:
rate_limits:
per_minute: 120
per_day: 50000
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640000000
Handling Rate Limits
import { RateLimitError } from 's4kit';
try {
await client.A_BusinessPartner.list();
} catch (error) {
if (error instanceof RateLimitError) {
// Wait and retry
await sleep(error.retryAfter * 1000);
await client.A_BusinessPartner.list();
}
}
Key Management
Viewing Keys
The dashboard shows:
- Key name and description
- Key prefix (e.g.,
sk_live_abc1...xyz9)
- Last 4 characters
- Created date
- Last used date
Editing Keys
Update key settings without regenerating:
- Click on the key
- Modify permissions or rate limits
- Click Save
Revoking Keys
Immediately invalidate a key:
- Click on the key
- Click Revoke
- Confirm revocation
Revoking a key immediately stops all requests using that key. This cannot be undone.
Key Rotation
Safe Rotation Process
- Create a new key with the same permissions
- Deploy the new key to your application
- Monitor both keys for a transition period
- Revoke the old key once no longer in use
Zero-Downtime Rotation
// Support multiple keys during rotation
const client = new S4Kit({
apiKey: process.env.S4KIT_API_KEY_NEW || process.env.S4KIT_API_KEY
});
Security Best Practices
Never Commit Keys
# .gitignore
.env
.env.local
.env.*.local
Use Environment Variables
// Good
const client = new S4Kit({
apiKey: process.env.S4KIT_API_KEY
});
// Bad - never hardcode keys
const client = new S4Kit({
apiKey: 'sk_live_abc123...'
});
Principle of Least Privilege
- Only grant permissions the key needs
- Use separate keys for different services
- Prefer read-only keys when possible
Monitor Usage
- Review API key logs regularly
- Set up alerts for unusual activity
- Revoke unused keys
Common Use Cases
Read-Only Analytics Key
For dashboards and reporting:
permissions:
production:
API_SALES_ORDER_SRV:
A_SalesOrder: [list, get]
A_SalesOrderItem: [list, get]
rate_limits:
per_minute: 30
per_day: 5000
Backend Service Key
For application backends:
permissions:
production:
API_BUSINESS_PARTNER:
"*": [list, get, create, update]
API_SALES_ORDER_SRV:
"*": [list, get, create, update]
rate_limits:
per_minute: 120
per_day: 50000
Development Key
For local development:
permissions:
sandbox:
"*":
"*": [list, get, create, update, delete]
rate_limits:
per_minute: 60
per_day: 10000
