Both the Services API and Devices API require an API-enabled Auvik user or service account with access to the data being requested.
A request may work for one tenant but return incomplete results or an authorization error when it includes multiple sub-tenants. This usually means the API user has not been granted access to every tenant included in the request.
Required permissions
Devices API
The API user or service account requires:
- API authentication enabled.
- Read access to device data.
- Access to the tenant or site containing the devices.
- Any additional read permissions required for related information, such as interfaces, components, lifecycle data, or discovery status.
Services API
The Services API requires the same base API access and read permissions as the Devices API.
For requests that span multiple tenants, the API user or service account must also be authorized to access each sub-tenant included in the request.
If the request includes additional data, such as statistics, alerts, or related inventory, the assigned role must include the corresponding API read permissions.
Multi-tenant scoping
A user’s API permissions and tenant access are separate considerations:
- The role determines which API resources the user can access.
- Tenant or site authorization determines which customer environments the user can query.
- Having permission to use an API does not automatically grant access to every sub-tenant.
- A request can return incomplete results when the API user is authorized for only some of the requested tenants.
A Super Admin with access to the parent and child tenants generally has the required scope, subject to the organization’s role and tenant configuration.
API Access Only service accounts must be explicitly granted access to every sub-tenant or client that should be included in API requests.
Grant access to additional sub-tenants
An Auvik administrator should:
- Create or locate the API service account.
- Assign the account an API-enabled role.
- Grant the account access to each sub-tenant or client that should be included in API requests.
- Confirm that the role includes the required read permissions for the Devices API, Services API, and any related resources.
- Document the tenants included in the integration scope.
For service-account configuration guidance, see API Access Only Role and Service Account Configuration in Auvik.
Verify API access
Test the integration in stages:
- Call a single-tenant Devices API or Services API endpoint.
- Confirm that the credentials and API permissions work.
- Call the equivalent request for each intended sub-tenant.
- Confirm that each tenant returns the expected data.
- Test the multi-tenant or aggregate request.
- Compare the returned tenant IDs with the documented integration scope.
Testing a single tenant first makes it easier to distinguish credential problems from multi-tenant authorization problems.
Common symptoms
The single-tenant request works, but the aggregate request is incomplete
The API user likely does not have access to every sub-tenant included in the request.
Confirm:
- The tenant IDs in the request are correct.
- The API user is authorized for each tenant.
- The service account has been assigned to every required client or site.
- The role includes the required API read permissions.
The request returns HTTP 403 Forbidden
A 403 response generally indicates that the API user lacks permission for the requested resource or is not authorized for the requested tenant.
Check:
- The assigned role.
- The API permissions required by the endpoint.
- Access to the requested tenant or sub-tenant.
- Whether the account is using the correct API credentials.
The request returns HTTP 404 Not Found
A 404 response may indicate an invalid endpoint, tenant ID, entity ID, or scope. Confirm that:
- The endpoint is correct.
- The tenant or entity IDs are valid.
- The requested object belongs to a tenant the API user can access.
- The API request is using the correct regional endpoint.
The request succeeds but returns no data
A successful response with no data may indicate:
- The tenant has no matching devices or services.
- The tenant or site scope is incorrect.
- Filters exclude the expected records.
- The API user does not have access to the tenant containing the data.
- Pagination has not been completed.
Verify the same data in the Auvik UI and compare the tenant and site identifiers returned by the API.
Best practices
- Use a dedicated service account for integrations.
- Grant only the API permissions required by the workflow.
- Explicitly document every tenant and site the service account can access.
- Preserve tenant IDs in integration records and downstream systems.
- Test one tenant before testing aggregate requests.
- Revalidate tenant access after adding or removing clients.
- Review service-account access when roles, sites, or organizational structures change.