Skip to Content
WorldsCredentials

Credentials

Two modes: permissive accepts any well-formed credential, enforced accepts only known ones.

Point your code at a sandbox and its credentials keep working. Nothing is provisioned, nothing is swapped, and no test-only branch is added.

Each twin has an auth row carrying a mode. It is per twin, and it starts permissive.

The two modes

Read down the column for the mode the twin is in.

Credential you sendpermissive (default)enforced
Well-formed, but not one the world knowsAcceptedThe vendor’s refusal
The one published in the twin’s own dataAcceptedAccepted
Absent, empty, or malformedThe vendor’s refusalThe vendor’s refusal

Your sk_test_… is well-formed, so under permissive it authenticates and you provision nothing to get started.

Under enforced, only credentials the world knows authenticate. Everything else gets the vendor’s real refusal, in the vendor’s own error shape.

Both modes refuse what the vendor refuses without a lookup: absent, empty, malformed, wrong shape. An unset environment variable fails here the way it fails in production.

Switching modes

# Arm the check
veris sandbox data set <twin> auth id=1 mode=enforced
 
# Back to the default
veris sandbox data set <twin> auth id=1 mode=permissive

<twin> is a name from veris sandbox services list. $CONTROL_URL is that twin’s control URL, printed by veris sandbox services get <twin>.

# Arm the check
curl -X PATCH "$CONTROL_URL/veris/data" \
  -H 'Content-Type: application/json' \
  -d '{"data": {"auth": [{"id": 1, "mode": "enforced"}]}}'
 
# Back to the default
curl -X PATCH "$CONTROL_URL/veris/data" \
  -H 'Content-Type: application/json' \
  -d '{"data": {"auth": [{"id": 1, "mode": "permissive"}]}}'

The credential the world knows is published in the twin’s own data, readable with veris sandbox data get <twin> <table> or at /veris/data. veris sandbox services manual <twin> names the table it sits in.

When to use enforced

Turn it on for a test that asserts your code handles a rejection: an expired key, a revoked token, a rotation that has not propagated yet. Turn it off again afterwards.

Leave it permissive the rest of the time. Under enforced, every test in the run has to carry a credential the world knows, which is setup you do not otherwise need.

In permissive mode a negative test must send no credential header at all. Any non-empty value is well-formed enough to pass, including an unresolved ${API_KEY} template your harness leaked into the header.

OAuth tokens

Access and refresh tokens are the exception in both modes. Only tokens the sandbox issued work.

Two ways to get one:

  • Run your application’s own connect flow against the twin. Better, because that flow is code under test too.
  • Read a seeded one with veris sandbox data get <twin> oauth_tokens, or from /veris/data?entity_type=oauth_tokens.

Do not insert tokens by hand.

Identity twins

For Google Drive, Gmail, Calendar, Jira, Microsoft Graph and Frame.io, token values are always checked and mode changes nothing. Those twins accept tokens minted by a companion identity twin in the same sandbox.

Each twin’s auth table says which kind it is.

Scopes

Where a vendor hangs permissions on a credential, the twin enforces them. A wrong token is a 401. A valid token missing a scope gets that vendor’s own 403, in that vendor’s own shape.

So a test that a read-only token cannot write is a real test here.

TimeFiles