> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Understanding API key permissions and scoping

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

```bash theme={null}
# 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](https://dashboard.artu.ai).

When creating an API key, you'll select:

1. **Name** - A descriptive name for the key
2. **Environments** - Which environments the key can access
3. **Permissions** - Which resources and operations are allowed

## Using API Keys

Pass your API key when initializing the SDK:

```typescript theme={null}
import { ComplianceSDK } from "@artu-ai/compliance-sdk";

const sdk = new ComplianceSDK({
  apiKey: process.env.ARTU_API_KEY!,
  environment: "test",
});
```

<Warning>
  The SDK will throw an error if you attempt an operation your API key doesn't
  have permission for.
</Warning>

## Permission Errors

If your API key lacks the required permission, you'll receive a `ForbiddenError`:

```typescript theme={null}
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

```bash theme={null}
# .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:

```typescript theme={null}
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
```