Environments

Thiqwave provides two isolated environments for every partner application: TEST and LIVE.

This mirrors the industry-standard model used by payment platforms — you build and test on TEST, then go live with LIVE. The two environments are completely separate: different credentials, different provider integrations, no cross-contamination of data.

TEST vs LIVE

	TEST	LIVE
Purpose	Development & QA	Production traffic
Network	Testnet / Sandbox	Mainnet / Production
Money movement	Simulated — no real funds	Real SAR / AED / USDT
Providers	Sandbox APIs (Lean, Wio, Fireblocks sandbox)	Production APIs
Key prefix	`tw_test_`	`tw_live_`
Rate limits	Relaxed	Production-grade
Data isolation	Fully separate from LIVE	Fully separate from TEST

Real money on LIVE

Any API call made with a LIVE credential can initiate real fund movement. Ensure your integration is fully validated on TEST before switching to LIVE.

Applications

Credentials in Thiqwave belong to an Application. An Application represents a single logical product or integration — for example, "My Payment App".

Each Application is created for a specific environment (TEST or LIVE). A typical setup has two applications with matching names:

Partner: Acme Corp
├── Application: "My Payment App" [TEST]   ← testnet credentials
└── Application: "My Payment App" [LIVE]   ← mainnet credentials

This gives you full lifecycle control per environment: you can independently generate, rotate, and revoke credentials for each without affecting the other.

Creating an Application

Step 1 — Register your company

Before creating an application, your company (Partner) must be registered. This happens once.

curl -X POST https://api.thiqwave.com/api/v1/auth/register \
  -H "Authorization: Bearer <keycloak-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Corp",
    "email": "dev@acme.com"
  }'

Step 2 — Create a TEST application

curl -X POST https://api.thiqwave.com/api/v1/applications \
  -H "Authorization: Bearer <keycloak-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Payment App",
    "environment": "TEST"
  }'

Response:

{
  "id": "01970000-0000-7000-8000-aaaaaaaaaaaa",
  "name": "My Payment App",
  "environment": "TEST",
  "is_active": true,
  "keycloak_client_id": null,
  "created_at": "2026-02-26T12:00:00.000Z",
  "updated_at": "2026-02-26T12:00:00.000Z"
}

Step 3 — Generate an API key

curl -X POST https://api.thiqwave.com/api/v1/applications/01970000-0000-7000-8000-aaaaaaaaaaaa/keys \
  -H "Authorization: Bearer <keycloak-token>" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "api_key_id": "01970000-0000-7000-8000-bbbbbbbbbbbb",
  "prefix": "a1b2c3d4",
  "type": "TEST",
  "expires_at": null,
  "created_at": "2026-02-26T12:00:00.000Z",
  "client_secret": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
}

Store the secret immediately

The client_secret is shown exactly once and is never stored in plaintext on our servers. Copy it to a secure secrets manager immediately. If you lose it, generate a new key and revoke the old one.

Step 4 — Repeat for LIVE

When your integration is validated on TEST, create a matching LIVE application:

curl -X POST https://api.thiqwave.com/api/v1/applications \
  -H "Authorization: Bearer <keycloak-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Payment App",
    "environment": "LIVE"
  }'

Then generate a key for it and store the LIVE secret separately from the TEST secret.

Authenticating API Calls

Use your client_secret in the X-API-Key header for all machine-to-machine API calls:

# TEST call — uses sandbox providers, no real money
curl https://api.thiqwave.com/api/v1/transactions \
  -H "X-API-Key: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

# LIVE call — uses production providers, real money
curl https://api.thiqwave.com/api/v1/transactions \
  -H "X-API-Key: <your-live-secret>"

The environment is determined by the key itself — you do not need to pass an environment parameter. A TEST key always hits sandbox providers; a LIVE key always hits production providers.

Key Management

List keys for an application

curl https://api.thiqwave.com/api/v1/applications/<app-id>/keys \
  -H "Authorization: Bearer <keycloak-token>"

[
  {
    "api_key_id": "01970000-0000-7000-8000-bbbbbbbbbbbb",
    "prefix": "a1b2c3d4",
    "type": "TEST",
    "expires_at": null,
    "created_at": "2026-02-26T12:00:00.000Z"
  }
]

Key hashes are never returned — only the prefix (first 8 characters of the secret) and metadata.

Generate a key with an expiry

curl -X POST https://api.thiqwave.com/api/v1/applications/<app-id>/keys \
  -H "Authorization: Bearer <keycloak-token>" \
  -H "Content-Type: application/json" \
  -d '{ "expires_at": "2027-01-01T00:00:00.000Z" }'

Revoke a key

curl -X DELETE https://api.thiqwave.com/api/v1/applications/<app-id>/keys/<key-id> \
  -H "Authorization: Bearer <keycloak-token>"

{
  "revoked": true,
  "key_id": "01970000-0000-7000-8000-bbbbbbbbbbbb",
  "revoked_at": "2026-02-26T14:30:00.000Z"
}

Revocation is immediate and irreversible. The key is rejected on all subsequent requests.

Security Best Practices

Never share secrets between TEST and LIVE. Store them in separate environment variables (THIQWAVE_TEST_SECRET, THIQWAVE_LIVE_SECRET).
Rotate keys every 90 days in production. You can have multiple active keys to make rotation zero-downtime.
Use key expiry for short-lived integrations or CI/CD pipelines.
Revoke old keys promptly — any key that may have been exposed should be revoked immediately.
Keep TEST traffic on TEST. Never use a LIVE key in development or staging infrastructure.

Application Lifecycle

Deactivating an application

If you need to disable an entire application (and all its keys) at once:

curl -X DELETE https://api.thiqwave.com/api/v1/applications/<app-id> \
  -H "Authorization: Bearer <keycloak-token>"

This is a soft-deactivation — all keys belonging to the application are immediately rejected. You can re-enable the application via PATCH /api/v1/applications/<app-id> with { "is_active": true }.

API Reference

Method	Path	Description
`POST`	`/api/v1/applications`	Create application
`GET`	`/api/v1/applications`	List applications
`GET`	`/api/v1/applications/:id`	Get application
`PATCH`	`/api/v1/applications/:id`	Update name or status
`DELETE`	`/api/v1/applications/:id`	Deactivate application
`POST`	`/api/v1/applications/:id/keys`	Generate API key
`GET`	`/api/v1/applications/:id/keys`	List keys
`DELETE`	`/api/v1/applications/:id/keys/:keyId`	Revoke key

TEST vs LIVE​

Applications​

Creating an Application​

Step 1 — Register your company​

Step 2 — Create a TEST application​

Step 3 — Generate an API key​

Step 4 — Repeat for LIVE​

Authenticating API Calls​

Key Management​

List keys for an application​

Generate a key with an expiry​

Revoke a key​

Security Best Practices​

Application Lifecycle​

Deactivating an application​

API Reference​

Next Steps​