--- title: "API Authentication & Signature Mechanism" id: "1272" type: "docs" slug: "api" published_at: "2026-08-24T06:49:15+00:00" modified_at: "2026-08-26T02:14:15+00:00" url: "https://help-new-pro.partnershare.net/en/help/technical/api" markdown_url: "https://help-new-pro.partnershare.net/en/help/technical/api.md" excerpt: "PartnerShare API Authentication This article explains the server-side authentication method for PartnerShare’s open API. Integrators must include an API Key, a second-precision timestamp, and a signature with every request. PartnerShare recalculates the signature server-side using the API Secret to validate..." taxonomy_doc_category: - "Technical Integration" --- ![Image](https://help-new-pro.partnershare.net/wp-content/uploads/2026/01/lQLPJyGF1y8mfltQULD6hr47Eio3cwlDF3jyDucB_80_80-1.png) ## Getting Started 4 - [How to Launch Your Affiliate Program on PartnerShare](https://help-new-pro.partnershare.net/en/help/started/ipe) - [How to Create a Referral Program](https://help-new-pro.partnershare.net/en/help/started/createprogram) - [What Is Referral Marketing / “Old-Bring-New” Program](https://help-new-pro.partnershare.net/en/help/started/rmp) - [What is Affiliate Marketing?](https://help-new-pro.partnershare.net/en/help/started/marketing) ![合作伙伴管理 - PartnerShare](https://help-new-pro.partnershare.net/wp-content/uploads/2026/01/lQLPKHuo_8Hse9tQULBcxdOVHL3PdwlDF3jyDucC_80_80.png) ## Campaign Operations 5 - [Checking Partner Withdrawal Status](https://help-new-pro.partnershare.net/en/help/operations/withdrawal-2) - [Withdrawal Methods Supported for Partners](https://help-new-pro.partnershare.net/en/help/operations/wm) - [Affiliate Management](https://help-new-pro.partnershare.net/en/help/operations/promoter) - [Product Management](https://help-new-pro.partnershare.net/en/help/operations/product-management) - [Campaign Management](https://help-new-pro.partnershare.net/en/help/operations/campaign) ![支付与交易 - ParterShare](https://help-new-pro.partnershare.net/wp-content/uploads/2026/01/lQLPJwyP0mL5vltQULAn8_2d-Nx0hglDF3jyZ0QA_80_80.png) ## Payments&Transactions 2 - [Auto-Payout](https://help-new-pro.partnershare.net/en/help/payments/autopayout) - [Commission Settlement](https://help-new-pro.partnershare.net/en/help/payments/settlement) ![技术集成 - PartnerShare](https://help-new-pro.partnershare.net/wp-content/uploads/2026/01/lQLPJwDplrTBzltQULCNPWCeBswcaAlDF3jyZ0QB_80_80.png) ## Account Management 2 - [Business Certification Prompts](https://help-new-pro.partnershare.net/en/help/account/bcp) - [Team Management](https://help-new-pro.partnershare.net/en/help/account/team) ![技术集成 - PartnerShare](https://help-new-pro.partnershare.net/wp-content/uploads/2026/01/lQLPJwDplrTBzltQULCNPWCeBswcaAlDF3jyZ0QB_80_80.png) ## Technical Integration 5 - [Embedding PartnerShare into Your Product](https://help-new-pro.partnershare.net/en/help/technical/embedding) - [Conversion Event Postback](https://help-new-pro.partnershare.net/en/help/technical/event) - [Click-Tracking SDK Integration](https://help-new-pro.partnershare.net/en/help/technical/sdk2) - [API Authentication & Signature Mechanism](https://help-new-pro.partnershare.net/en/help/technical/api) - [PartnerShare Product-Authorized Login Integration Guide](https://help-new-pro.partnershare.net/en/help/technical/guide) ![常见问题 - PartnerShare](https://help-new-pro.partnershare.net/wp-content/uploads/2026/01/lQLPJwbpuanIXltQULBfzi8WsAsVUQlDF3jyDucA_80_80.png) ## Frequently Asked Questions 2 - [Withdrawal FAQ](https://help-new-pro.partnershare.net/en/help/faqen/faq) - [Legacy Help Center Entrance](https://help-new-pro.partnershare.net/en/help/faqen/legacyhelp) ![快速入门 - PartnerShare](https://help-new-pro.partnershare.net/wp-content/uploads/2026/01/lQLPJyGF1y8mfltQULD6hr47Eio3cwlDF3jyDucB_80_80.png) ## Changelog 2 - [Changelog – 2026.03.05](https://help-new-pro.partnershare.net/en/help/changelog/changelog-2026-03-05) - [Changelog – 2026.05.15](https://help-new-pro.partnershare.net/en/help/changelog/changelog-2026-05-15) View Categories ## *PartnerShare API Authentication* This article explains the server-side authentication method for PartnerShare’s open API. Integrators must include an API Key, a second-precision timestamp, and a signature with every request. PartnerShare recalculates the signature server-side using the API Secret to validate the request, preventing forgery, replay, or unauthorized calls. > **Key concepts:** API Key (identity), API Secret (server-side signing), 5-minute time window, SHA256 ## 1. Overview PartnerShare’s open API uses `API Key + API Secret + Timestamp + Signature` for authentication by default. The API Key identifies the calling product; the API Secret is used only to generate the signature server-side and is never sent directly with the request. **Confirm caller identity:** `X-Api-Key` identifies the product/tenant, ensuring the request comes from an authorized product. **Prevent request forgery:** The signature is generated using the API Secret — attackers who know the API Key still cannot construct a valid signature. **Reduce replay risk:** `X-Api-Timestamp` is only valid within a 5-minute window; expired requests are rejected. > **Security note:** The API Secret must be kept on the server side. It must never be exposed in browsers, mini-programs, mobile apps, public repositories, or shared Postman environments. ## 2. Getting your API Key and API Secret In the PartnerShare dashboard, go to the relevant product’s Developer Integration or Advanced Settings page to get that product’s API Key and API Secret. **Field responsibilities:** The `API Key` is sent in the request header to identify the calling product; the `API Secret` is only used locally to compute the signature and is never transmitted in plaintext. ## 3. Request header conventions When calling an authenticated open API endpoint, include the following headers: | Header | Required | Description | | --- | --- | --- | | X-Api-Key | Yes | The API Key PartnerShare assigned to your product, used to identify the calling product. | | X-Api-Timestamp | Yes | Second-precision timestamp. The server validates it’s within the allowed time window. | | X-Api-Sign | Yes | The SHA256 signature generated per this document’s rules. | | Content-Type | Yes | application/json recommended. | ### Header example: [#](#0-toc-title) **http** ``` POST /api/open/v1/track/conversion HTTP/1.1 Host: api-service.partnershare.net Content-Type: application/json X-Api-Key: pk_xxxxxxxxxxxxxxxxxxxxx X-Api-Timestamp: 1776677721 X-Api-Sign: 8473ee71d083d9d1650c0e9081b5777d5b6cde2508521d5322d603a007214afd ``` ## 4. Signature rules PartnerShare’s signature only uses request parameter **field names** in the calculation — not the field values. Header fields do not participate in the signature either. **Collect request parameters:** Merge top-level field names from the URL query, form body, and JSON body. **Lowercase all field names:** e.g., `Product_Key` becomes `product_key` for signing purposes. **Sort naturally:** The sort order must match the server’s — PHP can use `SORT_NATURAL`. **Join with `&`:** e.g., `extra&product_key&target_product_key&user_id`. **Append timestamp and API Secret:** The final string is `joined_field_names + timestamp + api_secret`. **Compute SHA256:** Hash the final string with SHA256 to get the hex signature. ### 4.1 Signature formula [#](#1-toc-title) **text** ``` sha256(sorted_lowercase_param_keys_joined_by_ampersand + timestamp + api_secret) ``` ### 4.2 Worked example [#](#2-toc-title) Request parameters: **json** ``` { "product_key": "your_product_key", "target_product_key": "target_product_key", "user_id": "user_10001", "extra": { "locale": "zh" } } ``` Field names included in the signature: **text** ``` product_key target_product_key user_id extra ``` Sorted and joined: **text** ``` extra&product_key&target_product_key&user_id ``` Assume: **text** ``` timestamp = 1776677721 api_secret = sk_your_api_secret ``` Final string to be signed: **text** ``` extra&product_key&target_product_key&user_id1776677721sk_your_api_secret ``` ## 5. Signature code examples ### 5.1 JavaScript [#](#3-toc-title) **javascript** ``` function makeSign(params, timestamp, apiSecret) { const keys = Object.keys(params) .map((key) => key.toLowerCase()) .sort((a, b) => a.localeCompare(b, undefined, { numeric: true })); const signString = keys.join('&') + timestamp + apiSecret; return CryptoJS.SHA256(signString).toString(CryptoJS.enc.Hex); } ``` ### 5.2 PHP [#](#4-toc-title) **php** ``` str: keys = sorted([key.lower() for key in params.keys()]) sign_string = "&".join(keys) + timestamp + api_secret return hashlib.sha256(sign_string.encode("utf-8")).hexdigest() ``` ## 6. Full request example Below is an example of the headers and body structure for a signup event postback request. Different endpoints may have different body fields, but the signature method is the same. **http** ``` POST /api/open/v1/track/conversion HTTP/1.1 Host: api-service.partnershare.net Content-Type: application/json X-Api-Key: pk_xxxxxxxxxxxxxxxxxxxxx X-Api-Timestamp: 1776677721 X-Api-Sign: 8473ee71d083d9d1650c0e9081b5777d5b6cde2508521d5322d603a007214afd ``` **json** ``` { "event_name": "signup", "invited_user_id": "user_10001", "invite_code": "abc123" } ``` **Field names signed in this example:** `event_name`, `invited_user_id`, `invite_code`, sorted and joined as `event_name&invite_code&invited_user_id`. ## 7. Common errors & troubleshooting ### 7.1 Why do I get “API Key or signature cannot be empty”? [#](#7-toc-title) Usually the request header is missing `X-Api-Key`, `X-Api-Timestamp`, or `X-Api-Sign`. Confirm the header names are spelled correctly and that no gateway/proxy is stripping custom headers. ### 7.2 Why do I get “invalid signature”? [#](#8-toc-title) Check specifically: whether you used the API Secret (not the API Key) to sign; whether field names are lowercased; whether the sort order matches; and whether the fields you signed exactly match the actual top-level fields in the request body. ### 7.3 Why does my signature work locally but fail in production? [#](#9-toc-title) A common cause is that the serialization format changes in production — e.g., JSON locally but form-encoded in production — or a reverse proxy alters the request body. We recommend logging the actual top-level field names sent to PartnerShare and comparing them. ### 7.4 How long is the timestamp valid? [#](#10-toc-title) Currently 5 minutes. Use a second-precision timestamp, and make sure your server clock is synced to standard time. ### 7.5 Can the API Secret be placed in the frontend? [#](#11-toc-title) No. If the API Secret is exposed, anyone can forge valid requests. Always generate the signature server-side; the frontend should only call your own backend. ## 8. Best practices - Keep the API Secret on the server only — never in frontend code, mobile app binaries, or public config. - Generate a fresh timestamp and signature for every request — never reuse a previous signature. - Log the list of field names used for signing before signing, to make debugging easier. - Use different API Key/Secret pairs for production and test environments. - If you suspect the API Secret has leaked, reset it immediately in the dashboard and update your server-side config. Updated on 26/08/2026 ###### Share This Article : - ![Image](https://help-new-pro.partnershare.net/wp-content/plugins/betterdocs/assets/images/social/share-icon.svg?v=4.3.4) - [https://www.facebook.com/sharer/sharer.php?u=https://help-new-pro.partnershare.net/en/help/technical/api](https://www.facebook.com/sharer/sharer.php?u=https://help-new-pro.partnershare.net/en/help/technical/api) - [https://twitter.com/intent/tweet?url=https://help-new-pro.partnershare.net/en/help/technical/api](https://twitter.com/intent/tweet?url=https://help-new-pro.partnershare.net/en/help/technical/api) - [https://www.linkedin.com/shareArticle?mini=true&url=https://help-new-pro.partnershare.net/en/help/technical/api](https://www.linkedin.com/shareArticle?mini=true&url=https://help-new-pro.partnershare.net/en/help/technical/api) - [https://pinterest.com/pin/create/button/?url=https://help-new-pro.partnershare.net/en/help/technical/api](https://pinterest.com/pin/create/button/?url=https://help-new-pro.partnershare.net/en/help/technical/api) [PartnerShare Product-Authorized Login Integration Guide](https://help-new-pro.partnershare.net/en/help/technical/guide) [Click-Tracking SDK Integration](https://help-new-pro.partnershare.net/en/help/technical/sdk2) 大纲 - [Header example:](#0-toc-title) - [4.1 Signature formula](#1-toc-title) - [4.2 Worked example](#2-toc-title) - [5.1 JavaScript](#3-toc-title) - [5.2 PHP](#4-toc-title) - [5.3 Go](#5-toc-title) - [5.4 Python](#6-toc-title) - [7.1 Why do I get "API Key or signature cannot be empty"?](#7-toc-title) - [7.2 Why do I get "invalid signature"?](#8-toc-title) - [7.3 Why does my signature work locally but fail in production?](#9-toc-title) - [7.4 How long is the timestamp valid?](#10-toc-title) - [7.5 Can the API Secret be placed in the frontend?](#11-toc-title)