API keys authenticate your application with the Artu API and control what operations you can perform.
Permission Scoping
API keys use a permission pattern that scopes access by environment, resource, and operation:
{environment}:{resource}:{operation}
Permission Components
| Component | Values | Description |
|---|
environment | test, live | Which environment to access |
resource | clients, transactions, alerts | Which resource to access |
operation | create, read, update, delete | What operations are allowed |
Example Permissions
# Read clients in test environment
test:clients:read
# Full client access in test
test:clients:create
test:clients:read
test:clients:update
test:clients:delete
# Read-only access to live transactions
live:transactions:read
# Full access to live clients
live:clients:create
live:clients:read
live:clients:update
live:clients:delete
Obtaining API Keys
Get your API keys from the Artu Dashboard.
When creating an API key, you’ll select:
- Name - A descriptive name for the key
- Environments - Which environments the key can access
- Permissions - Which resources and operations are allowed
Using API Keys
Pass your API key when initializing the SDK:
import { ComplianceSDK } from "@artu-ai/compliance-sdk";
const sdk = new ComplianceSDK({
apiKey: process.env.ARTU_API_KEY!,
environment: "test",
});
The SDK will throw an error if you attempt an operation your API key doesn’t
have permission for.
Permission Errors
If your API key lacks the required permission, you’ll receive a ForbiddenError:
import { ForbiddenError } from "@artu-ai/compliance-sdk";
try {
await sdk.clients.delete(clientId);
} catch (error) {
if (error instanceof ForbiddenError) {
console.log("Missing permission:", error.message);
// "API key lacks permission: test:clients:delete"
}
}
Best Practices
Use Separate Keys for Different Purposes
# .env.development
ARTU_API_KEY=key_with_test_permissions
# .env.production
ARTU_API_KEY=key_with_live_permissions
Principle of Least Privilege
Create API keys with only the permissions they need:
- Development keys: Full test access, no live access
- Production read-only: Read permissions only (e.g.,
live:clients:read) for dashboards
- Production full: All CRUD permissions for backend services
Rotate Keys Regularly
- Rotate API keys periodically
- Revoke keys immediately if compromised
- Use different keys for different services
Environment Mismatch
If you try to access an environment your key doesn’t have permission for:
const sdk = new ComplianceSDK({
apiKey: process.env.ARTU_API_KEY!, // Key with test-only permissions
environment: "live", // Requesting live access
});
// This will throw ForbiddenError
await sdk.clients.list();
// Error: API key lacks permission for live environment
