opendunes
Connect · 3 min
Copy page ▾

Sign in with OpenDunes

Give your app an API keyAPI keyThe key you create and send with every request that calls a model.More on API keys → on its user's balanceBalanceWhat you can spend, in DA.More on Balance and charges →, with the user's approval.

  1. Send the user to OpenDunes.
  2. Read the code on your callback.
  3. Exchange the code for a key.
  4. Call models with the key.

Your app never asks for a password or a card. The user signs in on OpenDunes, approves your app, and your app gets an API key of its own. Every request sent with that key is charged to the user's balance, never to yours. The flow is OAuth PKCE, with the S256 method.

1. Send the user to OpenDunes

Make a secret, the code verifier, and keep it in your app. Send the user to https://opendunes.com/auth with its SHA-256 hash, the code challenge, and the page of your app they come back to.

You sendHolds
callback_urlthe page of your app the user comes back to
code_challengethe SHA-256 hash of your code verifier, in base64url
code_challenge_methodS256
key_labelthe key's name, shown to the user before they approve

The samples make a verifier, print it as an export line, and print the address to open. The callback here is http://localhost:3000/callback: put your app's page in its place.

import base64
import hashlib
import secrets
import urllib.parse

AUTH_URL = "https://opendunes.com/auth"
CALLBACK_URL = "http://localhost:3000/callback"
KEY_LABEL = "Souk Bot"

verifier = secrets.token_urlsafe(48)
digest = hashlib.sha256(verifier.encode()).digest()
challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()

query = urllib.parse.urlencode(
    {
        "callback_url": CALLBACK_URL,
        "code_challenge": challenge,
        "code_challenge_method": "S256",
        "key_label": KEY_LABEL,
    }
)

print(f'export OPENDUNES_CODE_VERIFIER="{verifier}"')
print(AUTH_URL + "?" + query)
Don't

Don't put the code verifier in the address. Only its hash, the code challenge, travels to OpenDunes in this step.

Do

Do keep the code verifier with the user's session in your app, until step 3 sends it.

2. Read the code on your callback

On OpenDunes, the user signs in and sees your app's key, under the name key_label gave it. When they approve, OpenDunes sends them back to your callback_url with a code in the address:

Text
http://localhost:3000/callback?code=‹code›

Your app reads code from the address. To try the samples by hand, copy it from the browser's address bar into your terminal:

Shell
export OPENDUNES_AUTH_CODE="‹code›"

3. Exchange the code for a key

Send the code and the verifier to POST /v1/auth/keys. This call carries no key: the code and the verifier prove it is your app. The answer holds the user's new key in key.

You sendHolds
codethe code from the callback address
code_verifierthe secret you made in step 1
code_challenge_methodS256, as in step 1

The samples exchange the code, then read the new key back with This key, a route that charges nothing. The cURL tab reads the answer with jq.

import json
import os
import urllib.request

BASE_URL = "https://opendunes.com/v1"

body = json.dumps(
    {
        "code": os.environ["OPENDUNES_AUTH_CODE"],
        "code_verifier": os.environ["OPENDUNES_CODE_VERIFIER"],
        "code_challenge_method": "S256",
    }
).encode()
request = urllib.request.Request(
    BASE_URL + "/auth/keys",
    data=body,
    headers={"Content-Type": "application/json"},
)
with urllib.request.urlopen(request) as response:
    user_key = json.load(response)["key"]

check = urllib.request.Request(
    BASE_URL + "/key",
    headers={"Authorization": "Bearer " + user_key},
)
with urllib.request.urlopen(check) as response:
    print(json.load(response)["data"])
Do

Do keep the user's key on your server, next to the user's account in your app. It is an API key like any other: whoever holds it spends the user's balance.

4. Call models with the key

The user's key calls every route your own API key calls. Send it as Authorization: Bearer <key>, the way Quickstart sends yours. Each request is charged in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges → to the user's balance, the moment it ends, and usage.cost in the answer carries the charge (Balance and charges).

Watch out

When the user's balance is at zero or below, or cannot pay the request's hold, their key gets a 402, whatever is left on yours. Show the user the 402 and ask them to make a depositDepositMoney entering your balance, by CIB or Edahabia card.More on Balance and charges → on OpenDunes: Errors and retries.

Last modified on