> ## Documentation Index
> Fetch the complete documentation index at: https://openapidocs.flexforwardship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the Flex Forward API

# Authentication

All Flex Forward API endpoints require authentication via a **Bearer token** in the `Authorization` header.

## Getting your API token

API access tokens are issued by the Flex Forward team during onboarding or account approval. Contact us at [flex-forward.support@returnhelper.com](mailto:flex-forward.support@returnhelper.com) to request development or production access.

<Warning>
  Keep your API token secret. Do not share it in client-side code, public repositories, or insecure channels.
</Warning>

## How access works

Flex Forward uses a managed onboarding model. API access is provisioned by the Flex Forward team to ensure your account is configured correctly for your shipping lanes and courier requirements.

<Steps>
  <Step title="Contact the Flex Forward team">
    Email [flex-forward.support@returnhelper.com](mailto:flex-forward.support@returnhelper.com) with your use case, expected shipping volume, and required shipping lanes.
  </Step>

  <Step title="Receive development access">
    The team provisions your development credentials and configures your shipper account for testing against courier sandbox services.
  </Step>

  <Step title="Test your integration">
    Build and validate your integration using the [development environment](/environments). Verify label creation, document retrieval, and tracking.
  </Step>

  <Step title="Request production access">
    After successful testing, request production credentials. The team verifies readiness and provisions production access.
  </Step>
</Steps>

## Making authenticated requests

Include the token in the `Authorization` header of every request:

```bash theme={null}
curl -X POST https://api.flexforward.com/labels \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "ord-20250301-abc123",
    "courier": "yunexpress",
    "service": {
      "productCode": "HKMUZXR"
    },
    "shipment": { ... }
  }'
```

## Error responses

If the token is missing or invalid, the API returns a `401 Unauthorized` response:

```json theme={null}
{
  "error": "Unauthorized"
}
```

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

```json theme={null}
{
  "error": "Forbidden"
}
```

## Token best practices

* Rotate tokens regularly
* Use separate tokens for [development and production environments](/environments)
* Store tokens in environment variables or a secrets manager — never hard-code them