{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Reefpay Docs","description":"Reefpay is the groundbreaking payment gateway that lets you integrate with the future of payments."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"authentication","__idx":0},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every operation in the API is authenticated. A request needs two headers, and"," ","resellers acting for a merchant need a third."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-headers","__idx":1},"children":["The headers"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Header"},"children":["Header"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it carries"},"children":["What it carries"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Api-Key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The API key issued to your client"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Client-Id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your client's identifier, in the form ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CLIENT-01KFDKXMQ637EKEAY410MSQSXB"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Acting-As-Client-Id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The child client a reseller is acting for"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both required headers must be present. If either is missing, the request fails"," ","with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," and an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_code"]}," of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/transactions HTTP/1.1\nHost: https://api.dev.paradisegateway.net\nContent-Type: application/json\nApi-Key: $d48045e5-f017-4633-a5e7-4efb56f70afa\nClient-Id: CLIENT-01KFDKXMQ637EKEAY410MSQSXB\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always 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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"where-your-api-key-comes-from","__idx":2},"children":["Where your API key comes from"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A key is issued when the client is created. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/clients"]}," returns it on the"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api_key"]}," field of the response."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keys look like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pk_live_01KFDKXMQ637EKEAY410MSQSXB"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"acting-on-behalf-of-a-client","__idx":3},"children":["Acting on behalf of a client"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A reseller can send a request for one of its own merchants by naming that"," ","merchant in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Acting-As-Client-Id"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The reseller still authenticates as itself. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Api-Key"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Client-Id"]}," stay the"," ","reseller's; only the extra header changes."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"Api-Key: <the reseller's key>\nClient-Id: CLIENT-01KFDKXMQ637EKEAY410MSQSXB\nX-Acting-As-Client-Id: CLIENT-01KFDKXMQ637ETEAY410MSQTUH\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Three rules govern it:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["It works from a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["parent to its own children"]}," only."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A merchant has no children, so a merchant calling for itself omits the header."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sending your own client ID is not the same as omitting the header."]}," Some"," ","operations reject it."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/clients"]}," is the exception that proves the rule: the child does not"," ","exist yet, so there is nothing to act as."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":4},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/get-started/quickstart"},"children":["Process your first test sale"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/get-started/environments"},"children":["Choose an environment"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/get-started/errors"},"children":["Understand errors and retries"]}]}]}]},"headings":[{"value":"Authentication","id":"authentication","depth":1},{"value":"The headers","id":"the-headers","depth":2},{"value":"Where your API key comes from","id":"where-your-api-key-comes-from","depth":2},{"value":"Acting on behalf of a client","id":"acting-on-behalf-of-a-client","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Authentication","shortTitle":"Authentication","intro":"Every request to the {% $env.PUBLIC_BRAND_NAME %} API carries an API key and a client ID. This page covers both headers, plus the one resellers use to act for a merchant.","type":"how-to","seo":{"title":""}},"lastModified":"2026-09-17T04:46:31.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/get-started/authentication","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}