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 |
