The sandbox

The sandbox is a hosted copy of the identity provider that holds only fake people. You use it to build and test your server before your app is registered: there is nothing to sign up for and nothing to install.

Base address: https://superapp.ideapreneurnepal.com/sandbox

	Value
Client id	`sandbox_app`
Client secret	`sandbox_secret`
Fake users	`sita` (Sita Gurung), `bikash` (Bikash Rai), `asha` (Asha Tamang)

These credentials are public and the same for everyone. They only work in the sandbox.

How it replaces SuperPreneur#

In real life the SuperPreneur app delivers the launch token to your page. In the sandbox there is no phone app, so you ask the sandbox for a token yourself, for the nonce your server issued. Everything after that is identical to production: your server sends the token and nonce to the verify route with HTTP Basic credentials, and gets back sub, scopes and name.

Step	Production	Sandbox
Get a token for a nonce	The SuperPreneur app delivers it to your page	`POST /sandbox/api/launch/token`
Verify it	`POST /api/launch/verify`	`POST /sandbox/api/launch/verify`
Public keys	`/.well-known/jwks.json`	`/sandbox/.well-known/jwks.json`

The Playground does the first step for you, in your browser.

Ask for a token#

POST /sandbox/api/launch/token, no authentication, JSON body:

Field	Required	Description
`nonce`	yes	The nonce your server issued: 16 to 128 characters of letters, digits, hyphen and underscore
`client_id`	no	`sandbox_app` (default) or `sandbox_suspended`
`user`	no	`sita` (default), `bikash` or `asha`
`scenario`	no	One of the scenarios below. Default `ok`

curl -X POST https://superapp.ideapreneurnepal.com/sandbox/api/launch/token \
  -H 'Content-Type: application/json' \
  -d '{"nonce": "8nZk2Z-Msfpa9GWFqIiP__s6vgeizMt0", "user": "sita"}'

The answer has the token, which lasts 60 seconds:

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

Scenarios#

Each scenario produces the token your server must refuse. Your server should answer the user with a plain sentence and never create a session.

`scenario`	What verify answers	What it tests
`ok`	`200` with `sub`, `scopes`, `name`	The normal sign-in
`expired`	`400 expired`	A token that sat too long
`wrong_audience`	`400 wrong_audience`	A token meant for another app
`revoked`	`400 revoked`	A user who has withdrawn access
`invalid_token`	`400 invalid_token`	A token with a broken signature

Other behaviour to test:

To get	Do this
`401 invalid_client`	Verify with a wrong secret
`403 app_suspended`	Ask for a token with `client_id` `sandbox_suspended`, and verify with `sandbox_suspended` as the client id (secret `sandbox_secret`)
`400 nonce_mismatch`	Verify a token with a different nonce than it was issued for. The token stays usable for the right nonce
`400 replayed`	Verify the same token twice
`400 invalid_request`	Send a nonce that is too short

What is the same and what is not#

Same as production	Different
Token format, signature algorithm (EdDSA), 60 second life, single use	The signing key: tokens are signed with a sandbox key and carry `"sandbox": true`
Error codes and the shape of every answer	Users are fake, and `sub` values are different from the ones in production
`sub` is stable for one user in one app and different between users	Anyone can use the credentials, so never put real data here
Basic authentication on verify	Calls are limited to 120 a minute from one address

A sandbox token is refused by the hosted service, and a hosted token is refused by the sandbox, so a mix-up fails loudly.

From the browser#

The sandbox sends Access-Control-Allow-Origin: *, so a page on any site can call it. Your own server does not need this for the sandbox, only for the Playground.