Sandbox and testing

Environments, credentials, and the expected implementation and test process for a Swapnice pilot.

Partners integrate against sandbox first. Production credentials are issued after the sandbox checklist passes.

Environments

	Sandbox	Production
API base	https://api.sandbox.swapnice.com	https://api.swapnice.com
Data	Isolated fixtures and partner-generated test users	Live consented traffic
Secrets	Separate client_id / client_secret	Separate credentials; never reuse sandbox secrets
Rate limits	Generous for integration	Contractual
Consent	Real protocol, test users	Real users, production policy versions

Discovery: GET {base}/.well-known/oauth-authorization-server

Local Worker development (http://localhost:8787) is available for Swapnice-internal or white-glove sessions. Partner teams should treat sandbox as the source of truth unless we schedule a shared local walkthrough.

What you receive at kickoff

Swapnice issues:

• Sandbox app_id, client_id, and a one-time client_secret
• Allowed redirect URIs (you supply these first)
• Allowed scopes and consent purposes for the pilot
• A support alias for integration questions ([e-mail])

Store the secret in your secret manager. It is shown once. Rotation is done by Swapnice until self-serve dashboard rotation ships.

Suggested environment variables:

SWAPNICE_API_BASE_URL=https://api.sandbox.swapnice.com
SWAPNICE_CLIENT_ID=swa_client_...
SWAPNICE_CLIENT_SECRET=swa_secret_...
SWAPNICE_REDIRECT_URI=https://partner.example.com/swapnice/callback
SWAPNICE_ENV=sandbox

Expected implementation process

1. Read the contract

   Review SDK versus API, integration, data collection, and outputs before the technical session.

2. Register redirect URIs and scopes

   Send the exact sandbox and production redirect URIs, plus the scope template you intend to use. Swapnice configures the sandbox app.

3. Complete OAuth in sandbox

   PKCE authorize → token → introspect. Confirm token expiry and refresh before writing events.

4. Walk one test user through connect

   Create a customer, open connection_url, grant purposes, persist the receipt.

5. Send two event families

   One explicit claim (for example profile.selected) and one behavioral event (for example purchase.completed). Confirm 202, then GET /v1/events/:id until processed.

6. Read profile, claims, and intents

   Call the three read routes with consent_purpose. Confirm facts, alternatives, and a 403 after you revoke that purpose.

7. Register the webhook receiver

   Create the endpoint and verify signature handling. Live delivery is near-term; the receiver should still be ready.

8. Technical session

   Bring the payloads, failing cases, and scope questions. This is the meeting the docs are meant to make productive.

9. Production review

   Production app, production policy versions, go-live event list, and a revoke/suppression test.

Sandbox checklist

Use this as the acceptance list before asking for production.

• Sandbox token introspects with the expected scopes
• Redirect URI mismatches are rejected
• Customer upsert is idempotent on external_id
• Connection session expires if left unused
• Events without a receipt return consent_required
• Replaying the same Idempotency-Key returns the original event
• Changing the body on that key returns 409
• Profile read returns resolved facts after the archive processes
• Revoking a purpose blocks later events and purpose-scoped reads
• No secrets, emails, or payment tokens appear in payload or metadata
• Webhook receiver verifies the signing secret (even if delivery is still test-only)

Suggested test fixtures

Fixture	Value
Test customer external_id	sandbox_user_001
Purposes	personalization, analytics
Event A	profile.selected / attribute favorite series
Event B	purchase.completed / a catalog SKU
Negative test	Event for a purpose that is not granted
Revoke test	Revoke personalization, then retry Event B

Postman and cURL

Follow the request walkthrough for the full ordered sequence (authorize → customer → connect → consent → event → profile → revoke).

If you use Postman:

1. Do not use the built-in OAuth 2.0 helper. Authorize is a JSON POST with customer_id and PKCE.
2. Set collection auth to Bearer {{access_token}} after the token call.
3. Tokens expire in about 15 minutes. Re-run authorize + token when you see 401.
4. POST /v1/customers takes external_id, not customer_id.

Common errors

Error	Fix
invalid_client_id	Confirm the sandbox client Swapnice issued
invalid_grant	Code expired or reused — run authorize again
invalid_scope	Scope string must be space-separated and allowed on the app
invalid_redirect_uri	Must exactly match a registered URI
PKCE failure	code_verifier must pair with the S256 challenge
missing_bearer_token	Add Authorization: Bearer
401 on /v1/*	Token expired or missing scope
consent_required	Grant that purpose, or stop sending it
idempotency_key_required	Add Idempotency-Key on mutating calls
500 on /v1/customers	Body field is external_id, not customer_id

What “done” looks like for a pilot

The sandbox integration is complete when:

1. A test user can connect, grant, generate events, and appear in a profile read.
2. Revocation suppresses that user.
3. Your backend can call profile/intent reads without the client SDK.
4. You have a written list of production event types and purposes.

That is also the bar for scheduling the implementation working session: your engineers will have exercised the API and can ask specific questions.

Getting help

Email [e-mail] with:

• Sandbox app_id and request_id from the failing response
• Route, timestamp, and a redacted payload
• Whether the call came from the SDK or raw HTTP

Do not send client secrets or access tokens in email.