Permissions & Roles

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

User Role — hierarchical team membership role (JWT sessions)
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.

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

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	—

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

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`	—	—

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

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	—

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

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

Getting Started

Core Features

Configuration & Integrations

Developer Platform

Security

Permissions & Roles

Role Hierarchy

Locations

Secrets

Tasks

Executions

Vault Connections

Notifications

Audit Logs

Teams

Invitations

API Keys

Subscriptions & Billing

Usage

Scope Reference

​Role Hierarchy

​Locations

​Secrets

​Tasks

​Executions

​Vault Connections

​Notifications

​Audit Logs

​Teams

​Invitations

​API Keys

​Subscriptions & Billing

​Usage

​Scope Reference

Role Hierarchy

Locations

Secrets

Tasks

Executions

Vault Connections

Notifications

Audit Logs

Teams

Invitations

API Keys

Subscriptions & Billing

Usage

Scope Reference