opendunes
Management
Copy page ▾

Workload tokens

POST /v1/oauth/token trades a token your own identity provider signed for a short-lived access token that works as one of your API keysAPI keyThe key you create and send with every request that calls a model.More on API keys →; GET /v1/oauth/jwks answers the keys that sign access tokens.

Request

Neither route takes a key: the signed token is the proof. Use them where a job runs under an identity of its own, a CI job or a cloud function, so that no API key is stored there. For a key a user approves for your app, see Sign in with OpenDunes.

RouteKeyDoes
POST /v1/oauth/tokenno keytrades a signed token for an access token
GET /v1/oauth/jwksno keyanswers the public keys that sign access tokens

OpenDunes trusts an identity provider through a policy: its id, the provider's issuer and key address, the audience its tokens carry, the subject they may name, and the API key they act as. A policy is set up on OpenDunes' side; until one is, every exchange answers 401. Workload identity takes you through it.

Trade a token

POST /v1/oauth/token takes a form, application/x-www-form-urlencoded, or JSON. The token you send carries the trusted issuer in iss, the trusted audience in aud, and a sub the policy trusts. It is signed with RS256.

FieldNeededYou send
grant_typeyesurn:ietf:params:oauth:grant-type:token-exchange
subject_tokenyesthe token your identity provider signed, up to 16 384 characters
subject_token_typeyesurn:ietf:params:oauth:token-type:jwt, or urn:ietf:params:oauth:token-type:id_token
federation_policy_idyesthe id of the policy that trusts the provider: only that policy is checked
requested_token_typenourn:ietf:params:oauth:token-type:access_token, the only one
scopenoinference, the only one

Souk Bot's nightly job reads the token its CI gave it from WORKLOAD_TOKEN, trades it, then reads the key the access token acts as with This key, a route that charges nothing.

import json
import os
import urllib.parse
import urllib.request

ADDRESS = "https://opendunes.com/v1/oauth/token"
KEY_ADDRESS = "https://opendunes.com/v1/key"
WORKLOAD_TOKEN = os.environ["WORKLOAD_TOKEN"]
POLICY_ID = os.environ["POLICY_ID"]

form = urllib.parse.urlencode(
    {
        "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
        "subject_token": WORKLOAD_TOKEN,
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "federation_policy_id": POLICY_ID,
    }
).encode()
with urllib.request.urlopen(urllib.request.Request(ADDRESS, form)) as r:
    access_token = json.load(r)["access_token"]

check = urllib.request.Request(
    KEY_ADDRESS,
    headers={"Authorization": "Bearer " + access_token},
)
with urllib.request.urlopen(check) as response:
    print(json.load(response)["data"])

The signing keys

GET /v1/oauth/jwks takes no field. Read it to check an access token's signature on your own side.

import json
import urllib.request

ADDRESS = "https://opendunes.com/v1/oauth/jwks"

with urllib.request.urlopen(ADDRESS) as response:
    for key in json.load(response)["keys"]:
        print(key["kid"], key["alg"])

Response

POST /v1/oauth/token answers 200 OK:

FieldHolds
access_tokenthe access token: send it as Authorization: Bearer <access_token>, or as x-api-key, on any route an API key calls
token_typeBearer
issued_token_typeurn:ietf:params:oauth:token-type:access_token
expires_inseconds until the access token stops working: 900 at most, and never past the token you traded
scopeinference

The access token acts as the API key the provider is trusted for: it spends that key's cap and your balanceBalanceWhat you can spend, in DA.More on Balance and charges →, and it stops the moment that key is paused or deleted.

GET /v1/oauth/jwks answers 200 OK:

FieldHolds
keysthe keys that sign access tokens; an empty list when none is set up
ktyEC
crvP-256
usesig
algES256
kidthe key's id, as the kid in an access token's header
x · ythe public key's coordinates, in base64url

Both answers, illustrative:

JSON
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Im9w…",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "inference"
}
JSON
{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "use": "sig",
      "alg": "ES256",
      "kid": "opendunes-1",
      "x": "SAT6302t0ZCuZ4jU6tMwhmd0mdNAkSDCZRQmBGqQiyY",
      "y": "HTj_S_2fHlYA5QwzEBa1nHc1PVhqvUAMjRt-VU9Br-s"
    }
  ]
}

What it cost

Free. Trading a token and reading the signing keys are never charged. A request sent with the access token is charged in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges → to your balance, and to the cap of the key it acts as.

Errors

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

StatusWhen
400grant_type, subject_token, subject_token_type or federation_policy_id is missing, or a field is not one of the values above; error.metadata.errors names the field
401no policy is set up, the policy id is not one, the token's issuer is not the policy's, the token does not verify against the provider's keys, its audience or its subject is not the policy's, or the key it would act as is not active
503no access token can be issued right now; Retry-After says when to ask again

Last modified on