REST API access denied for custom roles in part management despite correct permissions

PLM Oracle Agile PLM
, , , , , , , ,
1

We’ve created custom roles for our part management automation workflows in Agile 9.3.5, but users assigned these roles are getting 403 Forbidden errors when accessing the REST API. The same operations work fine through the Web Client UI, so the underlying permissions are correct.

API error response:

{
  "error": "Access Denied",
  "code": 403,
  "message": "Role 'CustomPartEditor' not authorized for API access"
}

The custom role has all necessary privileges for part management: create parts, edit attributes, manage BOM, etc. The API role-permission mapping seems to be the issue - it’s not recognizing our custom roles as valid for API operations.

This is blocking our entire automation integration. How do we configure API role-permission mapping for custom roles and troubleshoot automation integration issues?

2

Custom roles aren’t automatically granted REST API access in Agile. You need to explicitly enable API access for your custom role in the role configuration. Go to Admin > Roles & Privileges > [Your Custom Role] and check the “Allow REST API Access” checkbox. This is a separate permission from the functional privileges.

3

Test your custom role API access using the Agile API testing tool first before troubleshooting your automation code. This will help you determine if the issue is with the role configuration or with how your automation is authenticating. The testing tool can show you exactly which API endpoints are accessible with your custom role and which are being denied.

4

I’ve seen this exact issue. The REST API uses a different authentication and authorization mechanism than the Web Client. Your custom role needs to be added to the API authentication provider’s role mapping configuration. This tells the API layer which Agile roles should be recognized and what their permission scope is.

5

I’ll provide a complete solution for configuring API role-permission mapping, troubleshooting custom role access, and ensuring proper automation integration.

API Role-Permission Mapping:

The core issue is that Agile’s REST API maintains a separate authorization layer from the standard privilege system. Custom roles must be explicitly configured for API access in multiple locations:

  1. Enable API Access for Custom Role:

    • Navigate to Admin > Roles & Privileges > CustomPartEditor
    • In the Role Properties tab, enable “REST API Access”
    • Set API Access Level to “Full” (or “Read-Only” if appropriate)
    • Save the role configuration

  2. Configure API Role Mapping: Edit the rest-api-config.xml file (located in <AGILE_HOME>/config/):

<api-role-mappings>
  <role-mapping>
    <agile-role>CustomPartEditor</agile-role>
    <api-privileges>
      <privilege>part.create</privilege>
      <privilege>part.read</privilege>
      <privilege>part.update</privilege>
      <privilege>bom.manage</privilege>
    </api-privileges>
  </role-mapping>
</api-role-mappings>

This mapping tells the REST API which operations to allow for your custom role. The privileges should match the functional capabilities your role needs.

  1. Update API Authentication Provider: Modify the authentication provider configuration to recognize your custom role:
<authentication-provider>
  <recognized-roles>
    <role>CustomPartEditor</role>
  </recognized-roles>
</authentication-provider>

Without this, the API authentication layer won’t process your custom role even if it exists in Agile.

Custom Role Troubleshooting:

Systematically verify each layer of API access:

  1. Test Role Privileges: Log into Web Client as a user with CustomPartEditor role. Verify all part management operations work correctly. This confirms the underlying Agile privileges are properly configured.

  2. Enable API Debug Logging: Add to agile.properties:


log4j.logger.com.agile.api.rest=DEBUG
log4j.logger.com.agile.security.api=DEBUG
  1. Test API Access Directly: Use curl or Postman to test API authentication:
curl -X GET "https://agile-server/Agile/RESTService/api/v1/parts" \
  -H "Authorization: Bearer {token}" \
  -H "X-Agile-Role: CustomPartEditor"

The X-Agile-Role header explicitly specifies which role to use for the API request. This is critical when users have multiple roles assigned.

  1. Review API Error Logs: After a failed API call, check the REST API logs (rest-api.log) for detailed error information:
    • “Role not found” = Role mapping issue in rest-api-config.xml
    • “Insufficient privileges” = API privilege mapping is incomplete
    • “Authentication failed” = Role not recognized by authentication provider

Automation Integration:

For your automation workflows to work properly with custom roles:

  1. Configure Automation Client Authentication: Your automation scripts must authenticate with role specification:
import requests

headers = {
    "Authorization": f"Bearer {access_token}",
    "X-Agile-Role": "CustomPartEditor",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://agile-server/Agile/RESTService/api/v1/parts",
    headers=headers
)

The X-Agile-Role header ensures the API uses your custom role’s permissions instead of defaulting to a different role the user might have.

  1. Implement Role-Based API Client: Create a reusable API client class that handles role-specific authentication:
class AgileAPIClient:
    def __init__(self, base_url, token, role):
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {token}",
            "X-Agile-Role": role
        }
  1. Handle Multi-Role Scenarios: If your automation users have multiple roles, implement role selection logic:
def get_optimal_role(user_roles, required_operation):
    # Map operations to roles with necessary privileges
    if required_operation == "create_part":
        return "CustomPartEditor"
    elif required_operation == "approve_change":
        return "ChangeApprover"

Complete Implementation Checklist:

  1. ✓ Enable “REST API Access” in custom role configuration
  2. ✓ Add role mapping to rest-api-config.xml with all required API privileges
  3. ✓ Update authentication provider to recognize custom role
  4. ✓ Restart Agile application server to load configuration changes
  5. ✓ Enable API debug logging for troubleshooting
  6. ✓ Test API access using curl/Postman with explicit role header
  7. ✓ Update automation scripts to include X-Agile-Role header
  8. ✓ Verify all API endpoints needed by automation are accessible

Validation Testing:

Test your configuration with these scenarios:

  1. Single Role User: User with only CustomPartEditor role accesses API

    • Should succeed without X-Agile-Role header

  2. Multi-Role User: User with CustomPartEditor + other roles accesses API

    • Should succeed when X-Agile-Role: CustomPartEditor is specified
    • Should fail or use different permissions without role header

  3. Automation Client: Automated script creates part via API

    • Should succeed with proper authentication and role specification
    • Should handle 403 errors gracefully with retry logic

  4. Privilege Boundary: Test operations outside role privileges

    • Should fail with 403 for operations not in API privilege mapping
    • Error message should clearly indicate insufficient privileges

Common Pitfalls to Avoid:

  1. Configuration Caching: After modifying rest-api-config.xml, you MUST restart the Agile server. Configuration changes aren’t hot-reloaded.

  2. Role Name Case Sensitivity: Role names in API headers and configuration are case-sensitive. “CustomPartEditor” ≠ “customparteditor”.

  3. Incomplete Privilege Mapping: Map ALL required API privileges, not just the obvious ones. Missing even one privilege can cause cryptic 403 errors.

  4. Token vs Role Confusion: The authentication token identifies the USER, but the X-Agile-Role header specifies which of that user’s roles to use for authorization.

Performance Considerations:

For high-volume automation:

  1. Implement connection pooling in your API client to reuse authenticated sessions
  2. Cache role-to-privilege mappings to avoid repeated configuration lookups
  3. Use batch API operations when possible to reduce request overhead
  4. Monitor API response times - custom role authorization adds 5-10ms per request

With this complete configuration, your custom roles will work seamlessly with the REST API, enabling full automation integration for part management workflows. The key is ensuring proper mapping at all three layers: Agile role configuration, REST API configuration, and authentication provider configuration.

6

For automation integration specifically, you should verify that your API client is sending the correct authentication headers with the custom role information. The REST API requires explicit role specification in the request headers when multiple roles are available. If the role isn’t specified or is specified incorrectly, the API defaults to a minimal permission set and denies access. Check your automation scripts to ensure they’re including the role in the authorization header.

7

Even with API access enabled, custom roles need proper privilege mapping in the REST API configuration. The API has its own permission layer that maps Agile roles to API capabilities. Check the rest-api-config.xml file in your Agile server configuration. You’ll need to add your custom role to the appropriate API privilege groups. Without this mapping, the API layer doesn’t know what operations to allow for your custom role, even though the underlying Agile privileges are correct.