> For the complete documentation index, see [llms.txt](https://docs.parcellab.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.parcellab.com/docs/developers/getting-started/authentication.md). # Authentication Authentication is required when you interact with the parcelLab API to send tracking information or status updates. ## Overview You can send information to parcelLab to create trackings and status updates in our system via API. The parcelLab API uses your API token to securely authenticate requests. This means that to perform an action on the parcelLab API, you need to provide a valid API token in the `Authorization` header of the request. ## Authentication Process API requests are authenticated using an API token with the required scope. The header value is base64 of `account_id:token`, including the colon and without a trailing newline. The encoded value provided when you generate an API token in the parcelLab App is already in this format. Copy it as provided; do not encode it again. To authenticate a request, provide the API token in the `Authorization` header of the request. {% code overflow="wrap" %} ```python Authorization: Parcellab-API-Token ``` {% endcode %} ### Public and Private Endpoints Most endpoints in the parcelLab API require authentication. However, some endpoints are publicly available (that is: do not require authentication). These can be accessed by entering the relevant parameters in the query URL (for example: linking to the Order Status page). ### Access by Endpoint For a server integration that uses API tokens, use the following access rules. Account permissions still apply to authenticated endpoints. | Endpoint | API token | Scope or access requirement | | ---------------------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `GET /v4/track/orders/` and order detail | Required | `read`. A token with `track:read` is also accepted. | | `POST /v4/track/orders/` and `PUT /v4/track/orders/` | Required | `write`. A token with `track:write` is also accepted. | | Return registration list, detail, create, update, and mutation endpoints | Required | `read` for reads and `write` for writes. Tokens with `returns:read` or `returns:write` are also accepted. | | `POST /v4/returns/return-registrations/lookup-order/` | No | Order lookup and recipient verification defined by the Returns Portal configuration. Rate-limited to 10 requests per hour per client. | | Return registration article info, status, return options, exchange options, and submit actions | API token or supported Returns Portal nonce | Use read or write scope as required by the HTTP method, or provide the valid registration-specific nonce in `x-parcellab-nonce` for supported Returns Portal actions. | | `GET /v4/track/orders/info/` and `/info-widget/` | Optional | Account and lookup identifiers are required as specified by the endpoint. Recipient email, postal code, or security hash verification can be required by account configuration. Public access does not imply access to all recipient data. | | `GET /v4/size-recommender/articles/` and recommendation endpoints | No | Supply `account_id`. See [Size Recommender](/docs/developers/size-recommender/size-recommender/api.md). | | `GET /v4/campaign/evaluate/` and `GET /v4/campaign/redirect/` | No | Supply the targeting or event parameters. Use the returned tracking URLs. See [Campaigns](/docs/developers/campaign-manager/campaigns.md). | {% hint style="info" %} The generated OpenAPI reference currently lists token authentication for the two campaign endpoints and `POST /v4/returns/return-registrations/lookup-order/`. Those declarations do not match the endpoints' access rules: these operations accept requests without an API token. Return order lookup still requires the order and recipient verification data defined by the Returns Portal configuration. {% endhint %} Use the operation reference for endpoints not listed here. Keep API tokens in server-side integrations. For a public page, use the endpoint’s public verification flow instead of exposing a token in browser code. ### API Tokens and Bearer Tokens A server integration can use a scoped API token directly. It does not need to exchange an account password for a Bearer token first. Use `Authorization: Parcellab-API-Token ` for the examples in this documentation. If your integration uses a separately provisioned OAuth or JWT flow, use that flow’s credential and token instructions; an API token is not interchangeable with a Bearer token. ### Token Generation The API token is generated in your [account settings in the parcelLab App](https://app.parcellab.com/service/account/apitoken/) or by our Support team. {% hint style="info" %} Use API tokens in the `Authorization` header with the `Parcellab-API-Token` scheme. Do not send API tokens as `Bearer` tokens; `Bearer` is only for JWT authentication. {% endhint %} The API token generated is base64 encoded together with your parcelLab account ID. The token identifies the account for authentication. An endpoint can still require an `account` field or query parameter to select the resource account; follow that endpoint’s request schema. ### Test Your Token Use a token with the `read` scope to list orders. A token with `track:read` is also accepted: ```bash curl --request GET 'https://api.parcellab.com/v4/track/orders/' \ --header 'Authorization: Parcellab-API-Token ' ``` A successful response contains an empty `results` array if the account has no orders. A token with only `write` scope does not grant read access. For a known shipment's checkpoints, use [Order Status](/docs/developers/status-updates/order-status.md). ### API Credentials When you onboard with parcelLab, you will receive the necessary API credentials. The API token is account-specific and will be valid to send requests to the parcelLab API unless it is revoked. You should never share or use the API token outside of your account to ensure the security and integrity of your data. When interacting with the parcelLab API, ensure that your API token is used properly and securely in the Authorization header. When you are up and running with the parcelLab API, you can also use [our designated endpoint to create, retrieve, and revoke API tokens](https://github.com/parcelLab/gitbook-documentation/tree/main/developers/api-access/tokens.md) for your account. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.parcellab.com/docs/developers/getting-started/authentication.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.