Developers

Appearance

API Authorization ​

This guide explains how authorization works in the VORTEX API and what situations will result in permission errors.

Understanding Authorization ​

Authorization determines what actions an authenticated user is allowed to perform. Even with valid authentication credentials (API key), you may encounter permission errors if you attempt to perform operations that your account is not authorized for.

User Roles ​

VORTEX API uses role-based access control with the following roles:

  • OWNER: All admin permissions and has the right to transfer org or delete org
  • ADMIN: Grant admin permissions and all devices access
  • USER: May be a Member (no system setting permission) or other customized roles

TIP

API keys inherit the permissions of the user who created them. An API key created by a USER will have the same customized permissions as that user. For more information on creating API keys, please refer to the API Authentication guide.

403 Forbidden Error ​

The 403 Forbidden status code indicates that you are properly authenticated, but you don't have permission to perform the requested action.

When You'll Get 403 ​

Insufficient Permissions

You will receive a 403 error when your role or customized permissions don't allow the requested operation.

Example:

sh
# USER role without permission trying to access a device
curl --request GET \
  --url https://api.dev.vortexcloud.com/v1/devices/DEVICE_ID \
  --header 'Authorization: Bearer YOUR_API_KEY'

# Response: 403 Forbidden
{
  "error": "Not authorized"
}

How to Fix 403 Errors ​

Check Your User Role and Permissions ​

Contact your organization administrator to verify your role and permissions. You can check your assigned role and customized permissions in the VORTEX Portal.

Verify API Key Creator's Permissions ​

Since API keys inherit the creator's permissions, ensure the API key was created by a user with appropriate permissions. If needed, create a new API key with a user account that has the required permissions.

TIP

For a complete guide on handling HTTP errors including 401, 403, 404, and others, please refer to the Error Handling guide.