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

# Permissions & Roles

> Complete reference of every API action, the minimum user role required, and the corresponding API key scope.

DataRaven uses a layered permissions model. Every request is authorized by checking two things:

1. **User Role** — hierarchical team membership role (JWT sessions)
2. **API Key Scope** — granular scope string (API key authentication)

A request succeeds when the caller meets **at least** the minimum role shown below, **or** presents an API key that includes the listed scope.

<Note>
  Some actions are **JWT-only** — they cannot be performed with an API key.
  These are marked with a **—** in the API Key Scope column.
</Note>

## Role Hierarchy

Roles are hierarchical — higher roles inherit all permissions of lower roles.

| Level | Role         | Description                                                 |
| ----- | ------------ | ----------------------------------------------------------- |
| 4     | **Owner**    | Full control including team deletion and ownership transfer |
| 3     | **Admin**    | All operations except team deletion                         |
| 2     | **Operator** | Day-to-day operations — run tasks, verify connections       |
| 1     | **Viewer**   | Read-only access across all resources                       |

***

## Locations

| Action                | Method   | Min. Role | API Key Scope      |
| --------------------- | -------- | --------- | ------------------ |
| Get provider defaults | `GET`    | Viewer    | `locations:read`   |
| Create location       | `POST`   | Admin     | `locations:create` |
| List locations        | `GET`    | Viewer    | `locations:read`   |
| Get location details  | `GET`    | Viewer    | `locations:read`   |
| Update location       | `PATCH`  | Admin     | `locations:update` |
| Verify location       | `POST`   | Operator  | `locations:verify` |
| Delete location       | `DELETE` | Admin     | `locations:delete` |

## Secrets

| Action             | Method   | Min. Role | API Key Scope    |
| ------------------ | -------- | --------- | ---------------- |
| Create secret      | `POST`   | Admin     | `secrets:create` |
| List secrets       | `GET`    | Viewer    | `secrets:read`   |
| Get secret details | `GET`    | Viewer    | `secrets:read`   |
| Update secret      | `PATCH`  | Admin     | `secrets:update` |
| Delete secret      | `DELETE` | Admin     | `secrets:delete` |

## Tasks

| Action           | Method   | Min. Role | API Key Scope  |
| ---------------- | -------- | --------- | -------------- |
| Create task      | `POST`   | Operator  | `tasks:create` |
| List tasks       | `GET`    | Viewer    | `tasks:read`   |
| Get task details | `GET`    | Viewer    | `tasks:read`   |
| Update task      | `PATCH`  | Operator  | `tasks:update` |
| Disable task     | `POST`   | Operator  | `tasks:update` |
| Enable task      | `POST`   | Operator  | `tasks:update` |
| Archive task     | `POST`   | Operator  | `tasks:update` |
| Delete task      | `DELETE` | Admin     | `tasks:delete` |

## Executions

| Action                | Method | Min. Role | API Key Scope   |
| --------------------- | ------ | --------- | --------------- |
| Submit execution      | `POST` | Operator  | `tasks:execute` |
| Submit dry run        | `POST` | Operator  | `tasks:execute` |
| List executions       | `GET`  | Viewer    | `tasks:read`    |
| Get execution details | `GET`  | Viewer    | `tasks:read`    |
| Stop execution        | `POST` | Operator  | `tasks:execute` |
| Download logs         | `GET`  | Viewer    | `tasks:read`    |
| Stream logs (SSE)     | `GET`  | Viewer    | `tasks:read`    |

## Vault Connections

| Action                       | Method   | Min. Role | API Key Scope              |
| ---------------------------- | -------- | --------- | -------------------------- |
| Create vault connection      | `POST`   | Admin     | `vault_connections:create` |
| List vault connections       | `GET`    | Viewer    | `vault_connections:read`   |
| Get vault connection details | `GET`    | Viewer    | `vault_connections:read`   |
| Test vault connection        | `POST`   | Operator  | `vault_connections:test`   |
| Update vault connection      | `PATCH`  | Admin     | `vault_connections:update` |
| Rotate vault token           | `POST`   | Admin     | `vault_connections:rotate` |
| Delete vault connection      | `DELETE` | Admin     | `vault_connections:delete` |

## Notifications

| Action                   | Method   | Min. Role | API Key Scope          |
| ------------------------ | -------- | --------- | ---------------------- |
| Create notification      | `POST`   | Admin     | `notifications:create` |
| List notifications       | `GET`    | Viewer    | `notifications:read`   |
| Get notification details | `GET`    | Viewer    | `notifications:read`   |
| Update notification      | `PATCH`  | Admin     | `notifications:update` |
| Delete notification      | `DELETE` | Admin     | `notifications:delete` |
| Test notification        | `POST`   | Operator  | `notifications:test`   |

## Audit Logs

| Action          | Method | Min. Role | API Key Scope     |
| --------------- | ------ | --------- | ----------------- |
| List audit logs | `GET`  | Viewer    | `audit_logs:read` |

## Teams

| Action             | Method   | Min. Role | API Key Scope |
| ------------------ | -------- | --------- | ------------- |
| List my teams      | `GET`    | —         | —             |
| Get team details   | `GET`    | Viewer    | `teams:read`  |
| Create team        | `POST`   | —         | —             |
| Update team        | `PATCH`  | Admin     | —             |
| Delete team        | `DELETE` | Owner     | —             |
| Update member role | `PATCH`  | Admin     | —             |
| Remove team member | `DELETE` | Admin     | —             |

<Info>
  Team management actions (create, update, delete, member management) are **JWT-only**.
  API keys cannot create or modify teams.
</Info>

## Invitations

| Action                | Method   | Min. Role | API Key Scope |
| --------------------- | -------- | --------- | ------------- |
| List team invitations | `GET`    | Admin     | —             |
| Create invitation     | `POST`   | Admin     | —             |
| Revoke invitation     | `DELETE` | Admin     | —             |
| Resend invitation     | `POST`   | Admin     | —             |
| Get my invitations    | `GET`    | —         | —             |
| Accept invitation     | `POST`   | —         | —             |
| Decline invitation    | `POST`   | —         | —             |

<Info>
  All invitation actions are **JWT-only**. User-scoped endpoints (get/accept/decline) require only a valid session — no team role is needed.
</Info>

## API Keys

| Action              | Method   | Min. Role | API Key Scope |
| ------------------- | -------- | --------- | ------------- |
| Create API key      | `POST`   | Admin     | —             |
| List API keys       | `GET`    | Viewer    | —             |
| Get API key details | `GET`    | Viewer    | —             |
| Revoke API key      | `POST`   | Admin     | —             |
| Rotate API key      | `POST`   | Admin     | —             |
| Delete API key      | `DELETE` | Admin     | —             |

<Info>
  API key management is **JWT-only**. You cannot use an API key to create, revoke, or rotate other API keys.
</Info>

## Subscriptions & Billing

| Action              | Method | Min. Role | API Key Scope |
| ------------------- | ------ | --------- | ------------- |
| Get subscription    | `GET`  | Viewer    | —             |
| Verify subscription | `POST` | Viewer    | —             |
| Billing portal      | `POST` | Admin     | —             |
| Upgrade (checkout)  | `POST` | Admin     | —             |

## Usage

| Action         | Method | Min. Role | API Key Scope |
| -------------- | ------ | --------- | ------------- |
| Get team usage | `GET`  | Viewer    | `usage:read`  |

***

## Scope Reference

API key scopes follow the `resource:action` pattern. Here is the full list of available scopes:

| Scope                      | Description                                |
| -------------------------- | ------------------------------------------ |
| `audit_logs:read`          | List and view audit logs                   |
| `locations:create`         | Create new locations                       |
| `locations:delete`         | Delete locations                           |
| `locations:read`           | List and view locations                    |
| `locations:update`         | Update location properties                 |
| `locations:verify`         | Test location connectivity                 |
| `notifications:create`     | Create notification configurations         |
| `notifications:delete`     | Delete notification configurations         |
| `notifications:read`       | List and view notifications                |
| `notifications:test`       | Send test notifications                    |
| `notifications:update`     | Update notification configurations         |
| `secrets:create`           | Create new secrets                         |
| `secrets:delete`           | Delete secrets                             |
| `secrets:read`             | List and view secret metadata              |
| `secrets:update`           | Update secrets and rotate credentials      |
| `tasks:create`             | Create new tasks                           |
| `tasks:delete`             | Permanently delete tasks                   |
| `tasks:execute`            | Submit, stop, and dry-run executions       |
| `tasks:read`               | List and view tasks and executions         |
| `tasks:update`             | Update, enable, disable, and archive tasks |
| `teams:read`               | View team details                          |
| `usage:read`               | View team usage analytics                  |
| `vault_connections:create` | Create vault connections                   |
| `vault_connections:delete` | Delete vault connections                   |
| `vault_connections:read`   | List and view vault connections            |
| `vault_connections:rotate` | Rotate vault access tokens                 |
| `vault_connections:test`   | Test vault connectivity                    |
| `vault_connections:update` | Update vault connection properties         |