Going to production

You have a working integration in the sandbox. In this lesson you take it to production: the access request, the move from sandbox to production credentials, the checks before go-live, and how to run it safely afterwards.

Access goes through the hub, credentials come from the MDA

Production access is never granted by the hub, and never by the platform team on a phone call. The path is:

1. Access request on the Developer Hub. Choose the kind:
   • api_sandbox: a client on a test deployment, with synthetic data;
   • api_production: a production client;
   • register_data: reading a National Data Register register;
   • federation_node: connecting a ministry node to the national hub. Describe the target system or register, your organisation, the purpose, the legal basis, the data items, the expected volume, how long you retain data, and your safeguards.
2. Review. A reviewer at the MDA that owns the data checks the request and may ask for more information. They

   recommend approval or refusal.

3. Decision. A data steward decides. The person who recommends never decides, and nobody reviews or decides their

   own request.

4. Fulfilment. The owning MDA registers your client on the platform (or signs the data-sharing agreement) and the

   hub records which client was issued. The request is then fulfilled.

A request moves through submitted, more_info, recommended, then approved or rejected, and finally fulfilled; you may withdraw it before a decision. Every step is kept in the request's history.

Write the request carefully. Ask for the fewest scopes and data items that serve the purpose, and give a real retention period. Under the Data Protection Act No. 3 of 2021, collecting more than you need is not a technicality: a reviewer will refuse it.

Sandbox and production are separate

	Sandbox	Production
Credentials	Their own client ID and secret	A new client ID and secret; never reuse sandbox secrets
Data	Synthetic only	Real citizens' data, under the access you were granted
Providers	Test doubles or provider test tenants (ZamPay and ZamPass test)	The real providers
Seals	A development certificate authority	The national CA; production refuses development keys
Changes	Freely	Through change control

The client's environment label (sandbox or production) is shown by GET /api/v1/me. Make your configuration differ only by environment variables, never by code branches:

# production values come from your secret store, never from a file in the repository
GSB_API=https://platform.example/api/v1
CLIENT_ID=EXAMPLE01
CLIENT_SECRET=<from the secret store>
GSB_WEBHOOK_SECRETS=<from the secret store>

Never copy production data into the sandbox, and never put real personal data in test fixtures, screenshots or tickets.

The go-live checklist

Credentials and network

• The production client was registered by the owning MDA after an approved request.
• Secrets are in a secret store. They are not in source code, images, logs, tickets or chat.
• The client has an IP allow-list with your production addresses; you will tell the MDA before they change.
• You have rehearsed a secret rotation in the sandbox and know how to request one.

Calls

• Tokens are cached for their 15 minutes and renewed shortly before expiry.
• Errors are handled by code, and every error logs requestId.
• 429 waits for Retry-After; 5xx and 503 retry with back-off; validation errors are not retried.
• POST calls that need an Idempotency-Key send one, and reuse it on retry.
• Personal identifiers go in request bodies, never in URLs, and are never logged.

Webhooks

• The receiver is HTTPS on a public address and answers within 10 seconds.
• Signatures are verified over the raw body, with the 5-minute tolerance and constant-time comparison.
• Event ids are stored with a unique constraint; duplicates are acknowledged and ignored.
• A webhook.test from the MDA reached production and was processed.

Sign-in and documents (where relevant)

• ID tokens are fully validated; tokens stay on the server; back-channel logout is registered.
• Verification screens show seal and document status side by side, and say "could not check" on 503.

Federation

• For every flow, ask: does this still work when the service lives on another ministry node? Applying, paying,

  notifications, documents and verification must work whether the platform runs combined, as the hub, or as a node.

Running it

Watch your own signals. Track token failures, 4xx by code, 429s, webhook signature failures and processing lag. A rising number of INVALID_TOKEN or IP_NOT_ALLOWED usually means a configuration change on one side.

Know the MDA's view. The MDA's administrators see your client's calls, errors and latency per day and per route, and every webhook delivery with its attempts and errors. When you report a problem, give them the requestId or the X-GSB-Delivery-Id.

Recover from downtime. If your receiver was down longer than the retry window (about 22 hours), ask the MDA to replay the dead deliveries. If you have audit:read, you can also catch up from the audit trail from your last sequence number.

Respond to incidents. If a secret leaks, ask the MDA at once to rotate it with an overlap of 0, or to suspend the client: suspension takes effect on the next call, not when tokens expire. Then find out how it leaked.

Expect change. Within /api/v1 changes are additive. Ignore unknown fields and event types, and watch for Deprecation and Sunset headers in your logs.

Exercise

Draft the access request for a production integration you know: purpose, legal basis, data items, volume, retention and safeguards. Then remove every scope and data item that the purpose does not strictly need.

Check your understanding

• Who decides an access request, and who may not?
• Which four kinds of access request does the hub know?
• Why must production use a new client ID and secret instead of the sandbox ones?
• What is the first thing to ask the MDA when a secret leaks?
• How do you recover events missed during a long outage of your receiver?
• What question must you ask of every flow on a federated deployment?