Connect your app to Wajub
Get a merchant's key without asking them to copy it, through a pairing they approve in the Dashboard.
A plugin, a browser extension or a mobile app should not ask the merchant to copy a secret key.
It can ask for one instead, the way wajub login and the WordPress plugin's Connect with Wajub
do: the merchant approves the request in the Dashboard and your app receives a key once.
Start by opening a pairing session. Every field is optional.
| Field | What it does |
|---|---|
client_type | mobile, browser_extension, shopify, woocommerce, wordpress or other (cli when left out). Names your app on the approval screen and in the key's name, presented as your app's own claim |
device_name | Up to 120 characters shown to the approver, such as the store's name and domain |
environment | sandbox or live, the one you ask for. The approval page starts on Sandbox whatever you send |
permissions | The scopes your app needs, such as payment.write. The approval page then starts on a restricted key with them ticked |
return_url | A public address the approval page links back to once approved. It is never followed on its own |
client_key | Up to 60 characters of your own, kept with the session |
curl https://dashboard.wajub.com/api/apps/auth/sessions \
-H "Content-Type: application/json" \
-d '{
"device_name": "Boutique Amina, WooCommerce",
"client_type": "woocommerce",
"environment": "sandbox",
"permissions": ["payment.read", "payment.write", "refund.read", "refund.write"]
}'The answer carries the code the merchant sees, the token only your app holds, and the page to open. The session expires after 15 minutes. One address can open 30 sessions a minute.
Open confirm_url in the merchant's browser and show them the code. They sign in, check that the
page shows the same code, pick the environment, give the key every permission or a restricted
set, choose how long it lasts, 90 days or No expiry, and approve or refuse. Only the owner, an
Administrator or a Developer of the account can approve, or a Sandbox User for a sandbox key
only, after a security code, and Wajub e-mails the owner and every Administrator about every key
created this way. Meanwhile, poll every interval seconds with the polling token, 60 times a
minute at most.
curl https://dashboard.wajub.com/api/apps/auth/sessions/poll \
-H "Authorization: Bearer <polling_token>"| Answer | Meaning |
|---|---|
200 with status: pending | Not decided yet, poll again |
200 with status: authorized | The key, and what the merchant granted |
403 with status: denied | The merchant refused |
410 with status: expired | Nobody approved within 15 minutes, or the key was not collected within 15 minutes of the approval and was deleted |
410 with status: consumed | The key was already handed over |
404 | Unknown polling token |
Field of authorized | Holds |
|---|---|
key | The secret key: sk_test. or sk., rk_test. or rk. for a restricted one |
environment | sandbox or live: the one the merchant chose, whatever you asked for. Store the key there |
key_type, permissions | private with null for full access, or restricted with its scopes |
expires_at | When the key stops working, or null when it does not expire. key_expires_at holds the same value |
business | The name of the merchant's business |
client_type, api_base | Your client type, and the API to call |
The key is returned once, on the first authorized answer. Store it the way you would store any
secret key. A restricted key reaches GET / whatever it lacks, so read key_type and
permissions rather than probing the API. A wajub login key always lasts 90 days; for any other
client the merchant chooses.
When your app connects again, delete the key it replaces: DELETE /keys/current, sent with that
key, deletes a key a pairing created. It answers 409 for a key created in the Dashboard, which it
never touches, and 401 for a key already gone. Never send it from a copy of the installation that
may still share the key, such as a staging copy of a store.
curl -X DELETE https://api.wajub.com/keys/current \
-H "Authorization: sk_test.xxxxxxxxxxxxxxxx…"