Authentication

All Flex Forward API endpoints require authentication via two headers: x-rr-apikey and x-rr-apitoken.

Getting your API credentials

API credentials are managed in the Return Helper User Portal. You need a Return Helper user account — the same login you use for the Flex Forward Portal. Follow the steps in the Return Helper API authentication guide to locate or generate your credentials under Settings → Signing Key and API Token. You need both values shown there:

Credential	Header
API key	`x-rr-apikey: YOUR_API_KEY`
API token	`x-rr-apitoken: YOUR_API_TOKEN`

The same API key and API token authenticate both the Flex Forward API and the Return Helper User API:

API	How to authenticate
Flex Forward API	`x-rr-apikey` and `x-rr-apitoken`
Return Helper User API	`x-rr-apikey` and `x-rr-apitoken`

Every authenticated Flex Forward request must include both headers. Requests that omit either header, or that use only an Authorization: Bearer token, are not the documented customer authentication method.

Keep your API token and API key secret. Do not share them in client-side code, public repositories, or insecure channels.

How access works

Get your credentials

Go to Settings → Signing Key and API Token, or follow the Authentication instructions on the Return Helper API docs. Copy both the API key and the API token.

Authenticate Flex Forward requests

Include both x-rr-apikey and x-rr-apitoken on every request (see below). The same pair authenticates Return Helper User API calls.

Need help?

For account access, portal login issues, or other enquiries, contact [email protected].

Making authenticated requests

Include both headers on every request:

curl -X POST https://api.flexforward.com/labels \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "idempotencyKey": "unique-key-per-request",
      "courier": "yunexpress",
      "service": {
        "productCode": "HKMUZXR"
      },
      "label": {
        "format": "PDF"
      },
      "units": {
        "weight": "KG",
        "dimension": "CM"
      },
      "order": {
        "customerOrderNumber": "N-2026-05-27-TEST-03",
        "orderNumbers": {
          "platformOrderNumber": "platform-order-number",
          "referenceNumbers": [
            "ref-number-1",
            "ref-number-2"
          ]
        }
      },
      "shipment": {
        "shipTo": {
          "contact": {
            "firstName": "Alex",
            "lastName": "Smith",
            "phone": "8554377467",
            "email": "[email protected]"
          },
          "address": {
            "streetLines": [
              "18 Distribution Blvd"
            ],
            "city": "Edison",
            "state": "New jersey",
            "postalCode": "08817",
            "countryCode": "US"
          }
        },
        "shipFrom": {
          "contact": {
            "firstName": "John",
            "lastName": "Doe",
            "phone": "886900676877",
            "email": "[email protected]"
          },
          "address": {
            "streetLines": [
              "Habucho"
            ],
            "city": "Kishiwada-Shi",
            "state": "Osaka",
            "postalCode": "596-0825",
            "countryCode": "JP"
          }
        },
        "parcels": [
          {
            "weight": 0.5,
            "dimension": {
              "length": 30,
              "width": 20,
              "height": 10
            },
            "items": [
              {
                "descriptionEn": "Muji Ink pen",
                "descriptionLocal": "文具",
                "quantity": 1,
                "unitPrice": {
                  "amount": 29.99,
                  "currency": "USD"
                },
                "unitWeight": 0.5
              }
            ]
          }
        ]
      },
      "serviceOptions": [
        {
          "code": "V1",
          "value": "云途预缴"
        }
      ],
      "courierOptions": {
        "yunexpress": {
          "sourceCode": "YT",
          "sensitiveType": "D"
        }
      }
  }'

Error responses

If either credential is missing or invalid, the API returns a 401 Unauthorized response:

{
  "error": "Unauthorized"
}

If the credentials are valid but the caller does not have access to the requested resource, the API returns a 403 Forbidden response:

{
  "error": "Forbidden"
}

Credential best practices

Rotate API keys and tokens regularly
Use separate credentials for development and production environments
Store credentials in environment variables or a secrets manager — never hard-code them

Getting Started

Guides

Use-Case Guides

Platform

Authentication

Authentication

Getting your API credentials

How access works

Making authenticated requests

Error responses

Credential best practices

​Authentication

​Getting your API credentials

​How access works

​Making authenticated requests

​Error responses

​Credential best practices

Authentication

Getting your API credentials

How access works

Making authenticated requests

Error responses

Credential best practices