Introduction
The API access-only role in Auvik is designed for programmatic access to the platform without granting visibility into the user interface (UI). This role is commonly used for service accounts, automation workflows, integrations, and provisioning scripts that interact with Auvik via the API.
This article explains how the role works, what permissions it includes, and how to configure and troubleshoot service accounts that rely on API access.
Overview of the API Access Only Role
Users assigned the API access only role cannot access Auvik dashboards or most UI features. Their interaction with the platform is limited to:
- API-based operations
- Editing their own user profile
This makes the role suitable for:
- Automation scripts
- Third-party integrations
- Collector and installer provisioning workflows
Note: The permissions described below reflect the default configuration. This role can be edited to expand or restrict access as needed.
UI Access Limitations
By default, users with the API access only role have no access to nearly all UI screens.
No Access
- Audit logs (except billing changes)
- Billing
- Client management
- Collectors
- Company settings
- Configurations
- Data export
- Debug details
- Integrations
- Maintenance windows
- Manage alerts
- Notes
- Notification channels
- Remote browser
- Remote management audit logs
- Remote terminal
- Remote tunnel
- Reports
- Role management
- TrafficInsights
- Triggered alerts
- User management
- Manage features
- End user agents
- Remote support
- Endpoint monitoring
Limited UI Access
- User profile (edit only)
API Permissions Included
The API access only role includes a baseline set of API permissions.
Read (View) Access
- API – Alerts
- API – Audit history
- API – Components
- API – Configuration history
- API – Device details
- API – Device details (extended)
- API – Device info
- API – Entity notes
- API – Hardware lifecycle
- API – Interface info
- API – Network details
- API – Network info
- API – Usage
Access and Edit
- API – Tenants
Note: If your workflow requires additional API endpoints or write operations, you must modify this role or create a custom role.
Service Account Requirements
Service accounts are typically used to install collectors, provision integrations, or run automation scripts.
To function correctly, a service account must have:
- API authentication capability
- Token-based or key-based authentication
- Organization and site access
- Visibility into the target tenant(s) and site(s)
- Endpoint-level permissions
- Access to every API endpoint used by the workflow
Common Required Capabilities
Depending on the workflow, this may include:
- Registering or managing collectors
- Retrieving site configuration
- Listing devices
- Reading or updating integration settings
If the workflow performs write operations (e.g., POST, PUT, DELETE), the role must include write permissions for those endpoints.
Role Selection Strategy
Option 1: API Access Only Role (Default)
Use this role when:
- You need a baseline set of read permissions
- Your workflow does not require extensive write access
You can modify this role to add missing permissions.
Option 2: Custom Role
Use a custom role when:
- You need precise control over permissions
- The workflow requires specific endpoints not included by default
Always follow the principle of least privilege:
- Grant only the permissions required
- Avoid broad or unnecessary access
Troubleshooting API Permission Errors
API errors during installation or automation are commonly caused by missing permissions.
Step-by-Step Resolution
1. Identify the Failing Endpoint
From logs or API responses, capture:
- HTTP method (GET, POST, PUT, DELETE)
- Resource path
- Status code
2. Map Endpoint to Permission
Determine which API permission corresponds to the failing endpoint.
- If no matching permission exists in the assigned role, this is the cause of the failure
3. Update the Role
If using API access only role:
- Add permissions for the missing endpoints
- Ensure write permissions are included if required
If using a custom role:
- Add only the specific missing permissions
- Avoid expanding scope unnecessarily
4. Reassign and Refresh Credentials
- Confirm the service account has the updated role
- Generate a new API token if required
5. Retry the Workflow
- Re-run the installer or provisioning process
- Confirm that errors are resolved
Common Error Scenarios
401 Unauthorized
Typically caused by authentication issues:
- Invalid or expired API token
- Incorrect credentials
- API authentication not enabled for the account
If SSO or MFA is enforced:
- Ensure the service account uses supported token-based authentication
403 Forbidden
Indicates insufficient permissions:
- The role does not include the required API endpoint
- The operation (e.g., write) is not allowed
Site Scope Issues
- The role may not have access to the targeted site
- Ensure correct tenant/site scope is configured
Best Practices
- Use dedicated service accounts
- Avoid using personal user accounts for automation
- Apply least privilege access
- Grant only required API endpoints
- Rotate API tokens regularly
- Store tokens securely
- Document required endpoints
- Maintain a list of API calls used by your workflow
- Validate permissions during development
- Test with broader access, then reduce scope
Summary
The API access only role provides a secure foundation for API-driven workflows in Auvik by restricting UI access while enabling controlled programmatic interaction.
For successful automation and integrations:
- Ensure service accounts have the correct API permissions
- Map API errors directly to missing role permissions
- Use custom roles when more granular control is required
Proper role configuration and troubleshooting practices help maintain both security and operational reliability.