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

# Actor

> Understanding the actor concept for tracking who performs actions

<Info>
  **Beta Feature**: The Actor concept is currently in beta. Full support requires the new API key format which is not yet generally available. Contact [hi@nonce.app](mailto:hi@nonce.app) for early access.
</Info>

## Overview

An **Actor** represents an entity that performs actions in the Nonce system. The Actor concept provides a clear and unified way to identify **who** performed an operation, enabling comprehensive task audit capabilities.

With actors, you can:

* Track which user, API key, or system process created a task batch
* Build audit trails for compliance and operational visibility
* Distinguish between manual operations (users) and automated operations (API keys or system)

***

## Actor Types

| Type     | Description                                       | ID Prefix |
| -------- | ------------------------------------------------- | --------- |
| `user`   | A human user authenticated via the Nonce platform | `user_`   |
| `apikey` | An API key used for programmatic access           | `ak_`     |
| `system` | Internal system operations or automations         | -         |

***

## Actor Schema

When included in API responses, an actor contains the following fields:

| Field      | Type           | Description                                   |
| ---------- | -------------- | --------------------------------------------- |
| `type`     | string         | The actor type: `user`, `apikey`, or `system` |
| `id`       | string         | Unique identifier of the actor                |
| `name`     | string \| null | Display name of the actor                     |
| `avatar`   | string \| null | Avatar URL (for user actors)                  |
| `metadata` | object         | Additional metadata about the actor           |

### Example Actor Response

**User Actor:**

```json theme={null}
{
  "type": "user",
  "id": "user_2xGz1234567890",
  "name": "John Doe",
  "avatar": "https://example.com/avatar.png",
  "metadata": {
    "email": "john@example.com"
  }
}
```

**API Key Actor:**

```json theme={null}
{
  "type": "apikey",
  "id": "ak_abc123xyz",
  "name": "Production API Key",
  "avatar": null,
  "metadata": {
    "keyPrefix": "nonce_sk_..."
  }
}
```

**System Actor:**

```json theme={null}
{
  "type": "system",
  "id": "automation-system",
  "name": "Automation",
  "avatar": null
}
```

***

## Usage in API Responses

### Task Batches

When you retrieve task batches, the `created_by` field contains the actor who created the batch:

```json theme={null}
{
  "batch_id": "xxxxx-xxxxx-xxxx-xxxxxx",
  "task_name": "miner.power_mode.update",
  "status": "succeed",
  "task_count": 10,
  "succeed_count": 10,
  "failed_count": 0,
  "created_by": {
    "type": "user",
    "id": "user_2xGz1234567890",
    "name": "John Doe",
    "avatar": "https://example.com/avatar.png"
  },
  "created_at": "2024-01-15T10:30:00Z"
}
```

<Note>
  If the actor cannot be resolved (e.g., user was deleted), the `created_by` field may be `null` or contain an "Unknown" actor.
</Note>

***

## Current Limitations

<Warning>
  The Actor feature requires the new API key format to fully function. With legacy API keys, actor information may be limited or unavailable.
</Warning>

* **Legacy API keys**: Tasks created with legacy API keys may show limited actor information
* **System operations**: Some automated operations are attributed to the `system` actor
* **Historical data**: Older records may not have actor information populated

***

## Future Enhancements

Once the new API key format is generally available:

* Full actor tracking for all API operations
* Enhanced audit logging with actor information
* Actor-based filtering in list endpoints