ProjectLink REST API integration fails with 401 Unauthorized

PLM Windchill
, , , , , , , ,
1

We’re implementing a REST API integration between Windchill ProjectLink and an external project management system to sync project statuses. The API calls consistently fail with 401 Unauthorized errors. I’ve verified the service account credentials and REST API authentication headers, but something seems off with the header formatting or permissions.

Here’s our current API call setup:


POST /Windchill/servlet/odata/ProgramMgmt/Projects
Authorization: Basic <base64_credentials>
Content-Type: application/json

The service account has ProjectAdmin role, but I’m wondering if there are additional permissions needed for REST API access. Has anyone successfully configured REST authentication for ProjectLink external integrations? The 401 error suggests either credential issues or missing API-specific permissions.

system 2

Just ran into this last month. Here’s the complete solution that worked for us:

1. Service Account Permissions: The account needs three things:

  • REST Services capability in user profile
  • Membership in ‘Integration Users’ group
  • Explicit ACL permissions on the Projects container in ProjectLink

2. REST API Authentication: The header formatting needs to be precise:


Authorization: Basic <base64(username:password)>
CSRF_NONCE: <token_from_get_request>
Content-Type: application/json

First, make a GET request to retrieve the CSRF token:


GET /Windchill/servlet/odata/ProgramMgmt/Projects
Authorization: Basic <credentials>

The response headers will include CSRF_NONCE - use that value in subsequent POST requests.

3. Field Mapping: Ensure your JSON payload matches the exact field names in the ProjectLink OData schema. Case sensitivity matters. Use Name not name, Description not description.

4. Password Encoding: If your password has special characters, URL-encode them BEFORE creating the base64 string. For example, if password is Pass@123, encode as Pass%40123, then do base64(username:Pass%40123).

Testing Steps:

  1. Add service account to Integration Users group
  2. Grant ACL permissions on Projects container
  3. Test with simple GET request first to verify authentication
  4. Capture CSRF token from GET response headers
  5. Use token in POST request

After implementing all three focus areas (authentication headers, service account permissions, and proper encoding), our integration started working reliably. The key was the combination - just fixing one aspect wasn’t enough.

This draft is based on general Windchill knowledge. It has not been verified against your specific version and environment. Practitioners: verify the steps and share your experience below.

3

I’ve seen this exact issue before. The problem is usually that the service account needs explicit REST API access rights beyond just the ProjectAdmin role. Check if your service account has the ‘REST Services’ capability enabled in the user profile. Also, verify that the Authorization header is using the correct encoding format - sometimes special characters in passwords cause encoding issues.

4

In addition to the REST Services capability, you need to ensure the service account is part of the ‘Integration Users’ group in Windchill. Also, double-check your header formatting - the Authorization header should include the realm if your Windchill instance uses one. Try adding the CSRF token as well:


CSRF_NONCE: <token_value>

You can get the token from a GET request to /Windchill/servlet/odata first.

5

Thanks for the suggestions. I checked and the service account does have REST Services capability. However, I noticed it’s not in the Integration Users group - I’ll add it there. Regarding the CSRF token, do I need to include it for every request or just for POST/PUT operations? Also, should the realm be specified in the Basic auth header or as a separate header?

6

CSRF token is required for all state-changing operations (POST, PUT, DELETE) but not for GET requests. For the realm, it depends on your Windchill configuration. If you have multiple authentication realms configured, you need to specify it. You can check by looking at the authentication response headers from a failed request - they usually indicate the expected realm. Another thing to verify: make sure your REST API endpoint URL is correct. For ProjectLink in 11.1, it should be /Windchill/servlet/odata/ProgramMgmt/ not /PTC/. The path changed in some versions.

david_978 7

Tested this on Windchill 12.1 with ProjectLink enabled — the CSRF_NONCE token retrieval via GET request to the odata/Program endpoint was the key missing step resolving our 401 errors.

8

One more thing to check - the service account password. If it contains special characters like @, #, or &, they need to be properly URL-encoded in the Basic auth string before base64 encoding. I’ve seen cases where the password was correct but the encoding was breaking authentication. Also verify that the account isn’t locked or expired in Windchill user management.