TCC – Trados Cloud API Reference

Version 1.1.1 | January 2026

This appendix contains the essential Trados Cloud API information used by Trados Callback Catcher. For full details of how to work with the Trados Cloud API please refer to this site – https://developers.rws.com/ – and navigate to the appropriate product. You will find this to be a very comprehensive set of API documentation. But if you do have questions don’t be shy making use of the developer forums in the RWS Community. These forums are looked at daily by RWS developers and are the best source of information about the APIs for RWS products.

1. Authentication

Base API URL

https://api.{REGION_CODE}.cloud.trados.com/public-api/v1/

Region codes: eu, ca

Generating the Bearer Token

Trados Cloud uses Auth0 with the client credentials flow.

Request:

POST https://sdl-prod.eu.auth0.com/oauth/token
Content-Type: application/json
​
{
    "client_id": "{{Client ID}}",
    "client_secret": "{{Client Secret}}",
    "grant_type": "client_credentials",
    "audience": "https://api.sdl.com"
}

Response:

{
    "access_token": "eyJhbGciO....4NXz8TXatw",
    "expires_in": 86400,
    "token_type": "Bearer"
}

Required Headers

All API calls require:

Authorization: Bearer {{access_token}}
X-LC-Tenant: {{tenantId}}

Token Management

  • Tokens expire after 24 hours (expires_in: 86400)

  • Cache tokens until near expiry (e.g., 5 minutes before)

  • Limit token requests to maximum 16 per day

2. Webhooks Setup

Subscribing to Webhook Events

  1. Create a Service User in the correct customer folder

  2. Create an Application based on the Service User

  3. Configure webhooks in the Application settings:

    • Set Webhook URL (your endpoint)

    • Select event types to subscribe to

Webhook Scope

  • Webhooks trigger for all projects in the same folder as the Service User

  • Governed by inheritance – webhooks delivered only for users with READ permission on the triggering resource

Event Ordering

Webhook delivery order is not guaranteed. Use the timestamp field in payloads to determine chronological order.

Event Volume

Note that certain event types fire more frequently than expected:

  • PROJECT.TASK.CREATED fires for every task type in a project (copy-to-target, apply-perfect-match, pre-translation, etc.), not just user-facing workflow tasks

  • A single project creation can generate dozens of task events

  • Applications should be designed to handle high-volume webhook scenarios

3. Webhook Payload

Standard Payload Structure

{
    "eventId": "EVENT_ID",
    "eventType": "PROJECT.TASK.CREATED",
    "version": "1.0",
    "timestamp": "2025-01-15T10:30:00Z",
    "accountId": "ACCOUNT_ID",
    "data": {
        // Event-specific data
    }
}

Event Types

Event Data Model Trigger
PROJECT.CREATED project-event Create project
PROJECT.STARTED project-event Start project
PROJECT.UPDATED project-event Update/complete project
PROJECT.DELETED project-event Delete project
PROJECT.TASK.CREATED task-event Generate task
PROJECT.TASK.ACCEPTED task-event Accept task
PROJECT.TASK.COMPLETED task-event Complete task
PROJECT.TASK.UPDATED task-event Any task state change
PROJECT.TASK.DELETED task-event Delete project
PROJECT.SOURCE.FILE.CREATED source-file-event Add source file
PROJECT.SOURCE.FILE.UPDATED source-file-event Update source file
PROJECT.TARGET.FILE.CREATED target-file-event File format conversion
PROJECT.TARGET.FILE.UPDATED target-file-event Target file changes
PROJECT.ERROR.TASK.CREATED error-task-event Generate error task
PROJECT.ERROR.TASK.COMPLETED error-task-event Complete error task

4. Batched Webhooks

Multiple events can be delivered in a single HTTP request.

Batched Payload Structure

{
    "itemCount": 42,
    "items": [
        {
            "eventId": "EVENT_ID_1",
            "eventType": "PROJECT.CREATED",
            "version": "1.0",
            "timestamp": "TIMESTAMP",
            "accountId": "ACCOUNT_ID",
            "data": { ... }
        },
        {
            "eventId": "EVENT_ID_2",
            "eventType": "PROJECT.TASK.CREATED",
            "version": "1.0",
            "timestamp": "TIMESTAMP",
            "accountId": "ACCOUNT_ID",
            "data": { ... }
        }
    ]
}

Batch Configuration

  • Maximum batch size: 100 events

  • Maximum time interval: 1 second

  • Response timeout: 20 seconds (vs 3 seconds for single webhooks)

5. Webhook Request Headers

Signature & Verification Headers

Header Description
X-LC-Signature Digital signature for verification
X-LC-Signature-Algo Signing algorithm (e.g., “SHA256withRSA”)
X-LC-Transmission-Time Delivery timestamp (ISO 8601)

Correlation Headers

Header Description
X-Lc-Traceid Distributed tracing ID for support
X-LC-Region Account region

Delivery Headers

Header Description
X-LC-Retry-Num Retry attempt (0 = first attempt)
X-LC-Retry-Reason Previous error description
X-Forwarded-For Original client IP (when via proxy/tunnel)

Signature Verification

TCC verifies webhook signatures using RSA with SHA256:

  1. The signature is extracted from the X-LC-Signature header

  2. The public key (Secret Key) configured for the tenant is used

  3. Verification result is displayed as: ✓ valid, ✗ invalid, ○ skipped

Trace ID

The X-Lc-Traceid header enables distributed tracing across Trados Cloud infrastructure.

Usage: When raising support tickets with RWS, include this trace ID to enable server-side investigation of delivery issues. The trace ID is designed to be shared — it’s an opaque identifier that cannot be used to access accounts and is only meaningful to RWS engineers with backend access.

6. Response Requirements

Success

  • Return HTTP 2xx status code

  • Respond within 3 seconds (single) or 20 seconds (batched)

Retry Policy

Failed deliveries retry up to 8 times with exponential backoff:

Retry Delay Cumulative
1 5 min 5 min
2 10 min 15 min
3 30 min 45 min
4 2 hours 2h 45m
5 6 hours 8h 45m
6 10 hours 18h 45m
7 16 hours 34h 45m
8 24 hours 58h 45m

Circuit Breaker

3 consecutive timeouts trigger a 1-hour circuit breaker for that URL.

7. Service Users

Service users are non-human users for API integrations:

  • No login credentials

  • Access Trados Cloud only via API

  • Permissions determined by group membership

  • One service user per Application

Finding the Tenant ID

  1. Log in to Trados UI

  2. Select the account where the service user was created

  3. Profile → Manage Account → Account Information

  4. Copy Trados Account ID (24-character hex string)

Getting Current User (Service User Identity)

When authenticating with Client ID/Secret, the /users/me endpoint returns the service user:

Request:

GET /users/me?fields=id,name,description,email,userType,groups
Authorization: Bearer {{access_token}}
X-LC-Tenant: {{tenantId}}

Response:

{
    "id": "USER_ID",
    "name": "My Service User",
    "description": "Service user for webhook integration",
    "email": null,
    "userType": "serviceUser",
    "groups": [
        {
            "id": "GROUP_ID_1",
            "name": "Translators"
        },
        {
            "id": "GROUP_ID_2",
            "name": "Reviewers"
        }
    ]
}

TCC uses this to cache the service user’s ID and group memberships for task type highlighting.

8. Project Tasks API

Get Project Tasks

Retrieves all tasks for a project, including assignee information.

Request:

GET /projects/{projectId}/tasks?fields=taskType,taskType.key,taskType.name,taskType.automatic,status,createdAt,completedAt,outcome,input,assignees,assignees.user,assignees.group
Authorization: Bearer {{access_token}}
X-LC-Tenant: {{tenantId}}

Response:

{
    "itemCount": 5,
    "items": [
        {
            "id": "TASK_ID",
            "status": "created",
            "taskType": {
                "id": "TASK_TYPE_ID",
                "key": "engineering",
                "name": "Engineering",
                "automatic": false
            },
            "createdAt": "2025-01-15T10:30:00Z",
            "assignees": [
                {
                    "type": "user",
                    "user": {
                        "id": "USER_ID",
                        "name": "Service User",
                        "userType": "serviceUser"
                    }
                }
            ]
        },
        {
            "id": "TASK_ID_2",
            "status": "created",
            "taskType": {
                "id": "TASK_TYPE_ID_2",
                "key": "hold-for-feedback",
                "name": "Hold for Feedback",
                "automatic": false
            },
            "assignees": [
                {
                    "type": "group",
                    "group": {
                        "id": "GROUP_ID",
                        "name": "Reviewers"
                    }
                }
            ]
        }
    ]
}

Assignee Types

Tasks can be assigned to:

Type Description
user Direct user assignment (includes user.id, user.userType)
group Group assignment (includes group.id, group.name)
vendorOrderTemplate Vendor assignment
projectCreator Assigned to whoever created the project
projectManager Assigned to project manager

Task Type Highlighting Logic

TCC determines which task types to highlight by:

  1. Fetching service user identity (ID and group IDs) on tenant selection

  2. When webhooks arrive, querying project tasks with assignees

  3. Finding tasks where assignees include:

    • Direct user assignment: assignees[].user.id matches service user ID

    • Group membership: assignees[].group.id matches one of service user’s groups

  4. Extracting taskType.key from matching tasks

  5. Highlighting webhooks with those task type keys

9. API Rate Limits

Default Limits

Scope Per Second Per Minute Per Day
General API 10 200 200,000
Create Project 2 10 500
File Operations 5 200 5,000

Rate Limit Response

HTTP 429 Too Many Requests
​
{
    "errorCode": "TOO_MANY_REQUESTS_EXCEPTION",
    "message": "Quota exceeded. Please check X-RateLimit-Reset response header"
}

Headers:

  • X-RateLimit-Limit: Exceeded limit value

  • X-RateLimit-Reset: When to retry (RFC-1123 datetime)

  • X-RateLimit-Policy: Name of violated policy

TCC Rate Limit Mitigation

TCC uses debouncing to avoid hitting rate limits during webhook bursts:

  • Discovery API calls are debounced with a 2-second delay

  • Timer resets on each incoming webhook

  • Results in single API call batch per webhook burst

  • Prevents 10-20+ API calls from individual webhook arrivals

10. Troubleshooting Headers

TCC captures the following headers for troubleshooting webhook delivery issues. These headers are selected for their practical diagnostic value and are safe to share in support tickets or public documentation.

Timing & Delivery

Header Description Diagnostic Use
X-LC-Transmission-Time When Trados sent the webhook Calculate network latency

Retry Information

Header Description Diagnostic Use
X-LC-Retry-Num Retry attempt number (0 = first) Identify delivery failures
X-LC-Retry-Reason Why previous attempt failed Diagnose specific issues

Origin & Correlation

Header Description Diagnostic Use
X-Forwarded-For Original client IP (via tunnel) Verify Trados Cloud origin
X-Lc-Traceid Distributed tracing ID RWS support correlation
X-LC-Region Trados Cloud region Identify infrastructure

Source IP Ranges

Webhooks originate from Trados Cloud infrastructure hosted on AWS. Source IPs will vary based on region:

Region AWS Region
EU eu-central-1 (Frankfurt)
CA ca-central-1 (Montreal)

Note: Source IPs can change between requests due to load balancing. For firewall whitelisting, use AWS published IP ranges for the relevant region rather than specific IPs.