Authentication · API keys
POS credentials (API keys)
Enable POS for your organization to get a Client ID and a public key. Your server uses them to authenticate as a POS agent, then calls the API with the bearer token it receives.
The public key is a secret
Anyone holding your Client ID and public key can authenticate as your POS agent. Keep both on a trusted backend, never in browser or mobile code.
How it works
Enabling POS generates the credentials for an organization, parent or tenant. You then send them to the authenticate endpoint to receive an access token (see Access token). The management calls below are made by a signed-in user, so they carry that user's bearer token and an X-Client-Id header.
What to send as X-Client-Id
The organization's reference (its client identifier), the same value you use as orgReference in the path. The Client ID returned by POS is a different value: it is what your POS agent sends to authenticate.
/api/v1/organizations/pos/enableEnable or disable POS. Generates the public key.
/api/v1/organizations/{orgReference}/pos/keysReturns the Client ID and public key.
/api/v1/organizations/{orgReference}/pos/rotate-keyIssues a new public key and invalidates the previous one.
/api/v1/organizations/{orgReference}/pos/callback-urlChanges the https callback URL.
Enable POS
In the dashboard, open Integrations, choose Configure POS Integration, and select Activate Integration. With the API, call POST /api/v1/organizations/pos/enable with enablePos: true and your callback URL.
Send the request
orgReference, enablePos: true, and callBackUrl (https)
Read the PosResponse
id, publicKey, clientId, orgId, status ACTIVE, callBackUrl
Store the credentials
Move clientId and publicKey into your secret manager
Every response uses the standard envelope (statusCode, message, timestamp, data, successful). Success is 200.
View your Client ID and public key
The dashboard shows them under Configure POS Integration as Client ID and Client Secret (the public key, masked, with a copy button). With the API, call GET /api/v1/organizations/{orgReference}/pos/keys. The key can be retrieved again at any time while the integration exists, so it is not a one-time secret, but you should still treat it as one.
Public key
Retrievable with GET pos/keys[pos_public_key]Copied
Store keys safely
Do
- Use a managed secret store
- Restrict access by service role
- Redact the key from logs
Don't
- Commit the key to source control
- Paste it into tickets or chat
- Ship it in browser or mobile code
Rotate the key
Call POST .../pos/rotate-key to issue a new public key. The previous key stops working immediately, so update your POS agents right after rotating. Rotate on a schedule and whenever a key may have leaked.
Disabling is not a remedy for a leaked key
Disabling POS and enabling it again restores the same key. Use rotate-key instead.
Update the callback URL
PATCH .../pos/callback-url with { "callBackUrl": "https://..." } points the integration at a new URL. It must be https, up to 255 characters, and POS must have been enabled at least once. In the dashboard, edit the callback URL field and choose Save changes.
Disable POS
Call the enable endpoint again with enablePos: false, or choose Disconnect in the dashboard. The status becomes INACTIVE and invoices from your POS stop being sent automatically for validation and submission.
Troubleshooting
Failures use the same envelope with successful: false. The API documents 400, 401, 403, 404, 409, and 500. Check that your bearer token is current, that the X-Client-Id header is your organization's reference, and that the callback URL is https. See Errors.
Coming soon Soon
These are planned. They are not in the API today, so nothing above depends on them.
- Scopes, such as read-only access to invoices, so a key can do less than everything.
- Separate keys per environment, once sandbox and production exist.
- A dedicated revoke endpoint. Today you rotate a key, or disable and re-enable POS.