API reference

The routes a partner server calls on the identity provider. The same information is available as an OpenAPI 3.1 file, which you can load into Postman, Insomnia or any code generator.

This page is generated from that file, so the two always agree.

Servers#

Credentials for your app are issued when it is registered. To test before that, use the sandbox (client id sandbox_app, secret sandbox_secret).

POST /api/launch/verify#

Verify a launch token

Proves which user opened your app. Call it from your server with your client credentials, passing the token the page received and the nonce your server issued for that page load. On success the token is used up: a second call with the same token answers replayed. A call that fails because of a wrong nonce or wrong credentials does not use the token up.

Authentication: HTTP Basic: your client_id is the user name and your client_secret is the password.

Request body#

Example:

{
  "token": "eyJhbGciOiJFZERTQSIsImtp...Cjw40TDnu8Dg",
  "nonce": "8nZk2Z-Msfpa9GWFqIiP__s6vgeizMt0"
}

Responses#

200 response:

{
  "sub": "6wVFC8ZW-uir4EjfnDOwK95teeinCnN1NrjjLgXvNgQ",
  "scopes": [
    "profile"
  ],
  "name": "Demo Player"
}

400 response, replayed: The token was already used

{
  "error": "replayed"
}

400 response, nonce_mismatch: The nonce is not the one the token was issued for

{
  "error": "nonce_mismatch"
}

400 response, invalid_token: Not a valid token

{
  "error": "invalid_token"
}

400 response, invalid_request: A field is missing or malformed

{
  "error": "invalid_request",
  "detail": "nonce must be 16 to 128 characters: letters, digits, hyphen and underscore only.",
  "fields": {
    "nonce": [
      "nonce must be 16 to 128 characters: letters, digits, hyphen and underscore only."
    ]
  }
}

401 response:

{
  "error": "invalid_client"
}

403 response:

{
  "error": "app_suspended"
}

429 response:

{
  "error": "rate_limited",
  "detail": "Request was throttled. Expected available in 30 seconds.",
  "retry_after_seconds": 31
}

GET /.well-known/jwks.json#

Get the public signing keys

Optional. The public keys that launch tokens are signed with, as a JSON Web Key Set. Use them only if you also want to check a token's signature yourself; the verify route is still required. Cache the keys and fetch again when you meet a kid you do not know.

Authentication: none.

Responses#

200 response:

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "alg": "EdDSA",
      "use": "sig",
      "kid": "oGSRh-ZVy5_mJPgS",
      "x": "sMZWbe0Cf1cFc3PEcU_oJk-Gl9PenmDSj1l-JvNTmwE"
    }
  ]
}

POST /sandbox/api/launch/token#

Sandbox only: get a launch token

In production the SuperPreneur app delivers the launch token to your page. The sandbox has no app, so you ask for one here, for the nonce your server issued. Only the sandbox has this route. The token lasts 60 seconds and works once. Choose a scenario to get a token your server must refuse.

Authentication: none.

Request body#

Example:

{
  "nonce": "8nZk2Z-Msfpa9GWFqIiP__s6vgeizMt0",
  "user": "sita",
  "scenario": "ok"
}

Responses#

200 response:

{
  "token": "eyJhbGciOiJFZERTQSIs...",
  "expires_in": 60,
  "user": "Sita Gurung",
  "scenario": "ok"
}

400 response:

{
  "error": "invalid_request",
  "detail": "nonce must be 16 to 128 characters: letters, digits, hyphen and underscore only.",
  "fields": {
    "nonce": [
      "nonce must be 16 to 128 characters: letters, digits, hyphen and underscore only."
    ]
  }
}

Error codes#

Routes you implement yourself#

Your own server provides GET /api/config, POST /api/nonce, POST /api/session and your own protected routes. They are specified in the Server-side contract, not here, because they live on your server.