YaqeenDocs
Back to Yaqeen

How-to guide

The sandbox

Create a second organization of your own with made-up data and test keys, so you can try Yaqeen without touching real data.

The sandbox is a second organization that belongs to you. It has its own data and its own keys. Nothing in it can reach your real organization. This guide shows how to create it, fill it, use a test key and empty it. You need an admin session. A key cannot manage a sandbox.

Steps#

  1. Create the sandbox with POST /api/v1/sandbox/. The answer is 201 and {"exists": true, "slug": "example-sandbox"}. The slug is your organization slug plus -sandbox. You can have one.
  2. Fill it with POST /api/v1/sandbox/seed/. The answer is 201 and {"owners": 3, "stores": 3, "payouts": 6}.
  3. Make a test key with POST /api/v1/keys/ and "sandbox": true in the body. The key starts with yq_test_ and sees only the sandbox.
  4. Check what is inside with GET /api/v1/sandbox/. It returns exists, slug, and the number of stores, payouts and holds.

What the sample data holds#

The sandbox uses generated data. No real person, store or bank account is in it. It has three owners (sbx-o1 to sbx-o3) with one store each (sbx-s1 to sbx-s3). All three stores pay out to one bank account. There are six payouts (sbx-<tag>-p0 to sbx-<tag>-p5, where the tag is eight characters taken from your sandbox) of 500 to 700 SAR, with the deposit date of the day you filled the sandbox.

Make holds in the sandbox#

Filling the sandbox makes no holds. Ask your Yaqeen contact to score your sandbox. The recommended holds then appear in GET /api/v1/holds/?status=recommended.

A scoring run that you queue with POST /api/v1/scoring/runs/ as an admin runs on your real organization. It does not make holds in the sandbox. For the whole walk-through, see Your first hold in the sandbox.

What a test key can do#

A test key follows the same scope rules as a live key. See Authentication. With read, it reads the sandbox. With decide, it also decides sandbox holds. With ingest, it can send feed rows to the sandbox, so your system can test its own loading. A live key never sees sandbox data.

GET /api/v1/keys/ lists live and test keys together. The checklist in Set up your organization ignores the sandbox.

Empty the sandbox#

POST /api/v1/sandbox/reset/ deletes the sandbox data, including its holds, and returns the number of rows removed for each table. Your test keys stay. Fill it again afterward if you want the sample data back. Your real organization is never in scope.

If it does not work#

  • 409 exists: you already have a sandbox.
  • 409 no_sandbox: create the sandbox first. Seeding, resetting and making a test key all need it.
  • 409 not_empty: the sandbox already has data. Reset it, then fill it.
  • 403: you are not an admin, or you used a key.

For more, see Troubleshooting.

Next steps#

Up Down to moveEnter to openEsc to close