opendunes
Management
Copy page ▾

Sign-in keys

POST /v1/auth/keys trades a sign-in code for an API keyAPI keyThe key you create and send with every request that calls a model.More on API keys → that spends the user's balanceBalanceWhat you can spend, in DA.More on Balance and charges →; POST /v1/auth/keys/code creates a code with your own API key.

Request

These two routes end the sign-in flow. Sign in with OpenDunes walks through it from the approval page to the first call.

RouteKeyDoes
POST /v1/auth/keysno keytrades a code and its verifier for an API key
POST /v1/auth/keys/codeAPI keycreates a code on that key's own account, with no approval page

A code lives 10 minutes and trades once.

Trade a code

POST /v1/auth/keys takes JSON and no key: the code and its verifier are the proof.

FieldNeededYou send
codeyesthe code your callback address carried, or the id that POST /v1/auth/keys/code answered
code_verifieryesthe secret whose hash went out as code_challenge; with plain, the challenge itself
code_challenge_methodnoS256 or plain, the method the challenge was made with

The samples read the code and the verifier from the environment, as the guide's step 2 leaves them, and print the account the new key belongs to and the start of the key. Keep the whole key on your server, next to the user's account in your app.

import json
import os
import urllib.request

ADDRESS = "https://opendunes.com/v1/auth/keys"
CODE = os.environ["OPENDUNES_AUTH_CODE"]
VERIFIER = os.environ["OPENDUNES_CODE_VERIFIER"]

body = {
    "code": CODE,
    "code_verifier": VERIFIER,
    "code_challenge_method": "S256",
}
request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(body).encode(),
    headers={"Content-Type": "application/json"},
)
with urllib.request.urlopen(request) as response:
    answer = json.load(response)

print(answer["user_id"], answer["key"][:8])

Create a code

POST /v1/auth/keys/code takes JSON and your API key. The code it answers trades for a key on the account your key belongs to, so a tool of your own gets a key without the approval page.

FieldNeededYou send
callback_urlyesan https address, or http on localhost, 127.0.0.1 or [::1]; up to 2 048 characters
code_challengeyesthe SHA-256 hash of your code verifier, in base64url; with plain, the verifier itself
code_challenge_methodnoS256 or plain; absent, S256
key_labelnothe new key's name, up to 100 characters; absent, the host of callback_url
limitnothe new key's cap, in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges →; absent, no cap
usage_limit_typenowhen the cap starts again: daily, weekly or monthly, in UTC, the week from Monday; absent, never
expires_atnowhen the new key stops working, a date and time in the future; absent, never

Yacine gives Souk Bot's order tool a key of its own, capped at 500 DA a month. The figure is illustrative. Each sample makes a verifier, creates the code, and prints both as export lines for the trade above.

import base64
import hashlib
import json
import os
import secrets
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/auth/keys/code"
CALLBACK_URL = "http://localhost:3000/callback"

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

body = {
    "callback_url": CALLBACK_URL,
    "code_challenge": challenge,
    "code_challenge_method": "S256",
    "key_label": "Souk Bot orders",
    "limit": 500,
    "usage_limit_type": "monthly",
}
request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(body).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    code = json.load(response)["data"]["id"]

print(f'export OPENDUNES_AUTH_CODE="{code}"')
print(f'export OPENDUNES_CODE_VERIFIER="{verifier}"')

Response

POST /v1/auth/keys answers 200 OK. The new key carries the name, the cap and the end date the code was made with; on the approval page, the user sets its cap.

FieldHolds
keythe new key's secret, sk-...: answered once, and never again. It spends the balance of the account that approved
user_idthe id of that account

POST /v1/auth/keys/code answers 200 OK:

FieldHolds
datathe code
idthe code itself: send it as code to POST /v1/auth/keys
app_idnull
created_atwhen it was made, in UTC

Both answers, illustrative:

JSON
{
  "key": "sk-…",
  "user_id": "9d4c2e7a-1b3f-4e8d-a6c5-0f2b7d9e1a34"
}
JSON
{
  "data": {
    "id": "Xk2pQ9…",
    "app_id": null,
    "created_at": "2026-09-29T10:30:00+00:00"
  }
}

What it cost

Free. Creating a code and trading it are never charged. Every request the new key sends is charged in DA to the balance of the account it belongs to, and to its cap.

Errors

error.code carries the status, and error.message says why.

StatusWhen
400a field is missing or has the wrong type, callback_url is neither https nor http on your own machine, expires_at is in the past, the code is wrong, already traded or over 10 minutes old, the verifier does not match it; error.metadata.errors names the field
401on POST /v1/auth/keys/code: the key is missing, wrong, disabled or expired, or it is a management keyManagement keyThe key that runs your account through the API: the balance, the usage history, your keys, guardrails, observability. It never calls a model.More on API keys →
403on POST /v1/auth/keys/code: the key is kept to other addresses

Last modified on