Gateman environments

Gateman recognises three application environments:

production
staging
development

For an environment-aware operation, the calling application supplies its environment in that request. Gateman does not assign a persistent environment to an application, infer one from a domain or server, or silently choose a default. An application may make separate requests using different environments.

Staging and development currently have the same execution behaviour for the supported environment-aware provider capabilities. They remain separate accepted values so an application can identify which non-production environment made a request.

The calling application's environment is separate from Gateman's own deployment configuration. Environment selection is also separate from application authentication, HTTPS, and Contract v1 signing.

Supplying the environment

Environment-aware endpoints receive environment in the JSON request body:

{
  "environment": "staging",
  "keys": ["MY_API_KEY"]
}

The exact fields required in addition to environment depend on the selected route. The server requires a string, trims leading and trailing whitespace, converts it to lowercase, and accepts only production, staging, or development. Missing or invalid values produce a controlled HTTP 400 response.

The four official canonical clients can inject the configured application environment automatically for environment-aware routes. Configure the client once and use the same application integration code across environments. The clients reject a conflicting payload value locally. They do not send the environment through a separate authentication header, and environment selection does not introduce a separate signing rule; the JSON body is signed like any other Contract v1 request body.

See the individual PHP, Node.js, Python, and Go client guides for configuration details.

Environment-aware capabilities

The environment-sensitive routes are:

POST /send/ses
POST /send/postmark
POST /send/resend
POST /email/readiness
POST /twilio/sms/send
POST /telnyx/sms/send
POST /aws/sms/send
POST /stripe/request
POST /square/request
POST /paypal/request
POST /stripe/webhook-secret
POST /stripe/webhook/setup
POST /config/get
POST /secrets/get

Their provider behaviour is capability-specific.

Email

For SES, Postmark, and Resend:

Environment	Execution
`production`	Uses the configured email provider.
`staging`	Uses Gateman's local mailbox capture.
`development`	Uses Gateman's local mailbox capture.

Staging and development email capture does not deliver through the external email provider. Captured messages can be inspected through Gateman's mailbox facilities. Capture still performs the applicable local validation and consumes the applicable operation usage. Provider credentials are not necessarily required to execute a non-production capture; provider-specific application configuration, such as an SES sender address, may still be required.

SMS

For Twilio, Telnyx, and AWS SMS:

Environment	Execution
`production`	Uses the selected SMS provider.
`staging`	Uses Gateman's local SMS capture.
`development`	Uses Gateman's local SMS capture.

Staging and development capture do not send an SMS through the external provider. They do not use provider sandbox APIs. Applicable SMS operations consume operation usage regardless of environment.

Payments

Payment providers select environments according to their own integration rules:

Provider	`production`	`staging` and `development`
Stripe	Configured live Stripe credentials	Configured test Stripe credentials through Stripe's standard API origin
Square	Production credentials and the production Square endpoint	Test credentials and Square's sandbox endpoint
PayPal	Production credentials and the production PayPal endpoint	Test credentials and PayPal's sandbox endpoint

For Stripe, the effective live/test mode is determined by the credential supplied to Stripe. Gateman selects the configured live or test credential name but does not independently validate every supplied Stripe key's mode.

Stripe webhook-secret retrieval selects the webhook secret for the supplied environment. Stripe webhook setup operates against the provider environment selected by the applicable Stripe credentials and maintains separate environment-specific setup state.

Custom secrets

Custom secrets use one logical name with two optional values:

one production value;
one test value shared by staging and development.

The two values are independently optional and are managed under one logical custom-secret name in the customer console.

POST /secrets/get requires secrets:read, a credential request ID, and an environment. For a requested custom-secret name, selection is:

Environment	Returned value
`production`	Production value
`staging`	Test value
`development`	Test value

If the selected value is not configured, that requested name is omitted from the response. Gateman does not fall back to the other value.

Request:

{
  "environment": "staging",
  "keys": ["MY_API_KEY"]
}

Response when the test value is configured:

{
  "ok": true,
  "secrets": {
    "MY_API_KEY": "example-test-value"
  }
}

The example value is illustrative, not a real credential. Gateman returns only the selected value; it does not return both values in one response.

Provider-managed credentials

Custom-secret production/test pairing does not apply universally to provider-managed credentials. Provider integrations retain their own credential-selection rules.

For example, Stripe has live and test credentials, while Square and PayPal have production and test credentials. Email and SMS providers use their established provider configuration, with staging and development using local capture where supported.

Provider-managed values that are permitted through /secrets/get retain their existing provider retrieval permissions. Supplying an environment to /secrets/get does not convert those values into custom-secret pairs or change their provider retrieval authorization.

Environment-independent capabilities

These routes do not require an application environment:

POST /db/get
POST /s3/presign
POST /r2/presign
POST /turnstile/get
POST /recaptcha/get
POST /client/get

They follow their own request parameters and authorization requirements. Environment-independent does not mean read-only, simulated, uncharged, or safe for testing. For example, object-storage presigning uses caller-selected storage resources, and credential routes return app-authorized values without selecting an application environment.

Operation usage

Applicable billable operations consume Gateman operation usage regardless of whether the request uses production, staging, or development.

One operation is one operation. Staging and development do not provide separate free-operation allowances, and the environment does not change the operation's accounting rule merely because provider execution differs.

See Operation Accounting for the general accounting contract and the individual capability references for capability-specific operation details.

Email readiness

POST /email/readiness is a targeted provider-configuration check used by integrations such as WordPress. It requires an environment because it belongs to the environment-aware email integration contract, but it checks the selected provider's required application configuration rather than acting as a universal environment-health endpoint.

For example, an SES staging capture may still require sender configuration such as SES_FROM_EMAIL. An integration can use readiness results to warn about missing configuration before attempting email functionality.

Readiness does not prove successful external delivery, provide general provider monitoring, or establish production-versus-staging credential isolation. The exact requirements depend on the selected email provider.