Every operation in the API is authenticated. A request needs two headers, and resellers acting for a merchant need a third.
| Header | Required | What it carries |
|---|---|---|
Api-Key | Yes | The API key issued to your client |
Client-Id | Yes | Your client's identifier, in the form CLIENT-01KFDKXMQ637EKEAY410MSQSXB |
X-Acting-As-Client-Id | No | The child client a reseller is acting for |
Both required headers must be present. If either is missing, the request fails with 401 and an error_code of NOT_AUTHENTICATED — the same answer you get for a key that is wrong, so check that both are set before assuming the key is at fault.
POST /v1/transactions HTTP/1.1
Host: https://api.dev.paradisegateway.net
Content-Type: application/json
Api-Key: $d48045e5-f017-4633-a5e7-4efb56f70afa
Client-Id: CLIENT-01KFDKXMQ637EKEAY410MSQSXBAlways send these over HTTPS. An API key is a bearer credential with no cryptographic protection of its own, so anything that can read the request can replay it.
A key is issued when the client is created. POST /v1/clients returns it on the api_key field of the response.
That response is the only place the key appears. No later call returns it, and there is no endpoint that reads a key back. Store it when you create the client. If it is lost, the client needs a new key.
Keys look like pk_live_01KFDKXMQ637EKEAY410MSQSXB.
Keep the key out of source control, out of client-side code, and out of logs. Read it from an environment variable or a secrets manager at run time.
A reseller can send a request for one of its own merchants by naming that merchant in X-Acting-As-Client-Id.
The reseller still authenticates as itself. Api-Key and Client-Id stay the reseller's; only the extra header changes.
Api-Key: <the reseller's key>
Client-Id: CLIENT-01KFDKXMQ637EKEAY410MSQSXB
X-Acting-As-Client-Id: CLIENT-01KFDKXMQ637ETEAY410MSQTUHThree rules govern it:
- It works from a parent to its own children only.
- A merchant has no children, so a merchant calling for itself omits the header.
- Sending your own client ID is not the same as omitting the header. Some operations reject it.
POST /v1/clients is the exception that proves the rule: the child does not exist yet, so there is nothing to act as.