# 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:

```json
{
  "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](https://docs.getgateman.com/canonical-client-php/), [Node.js](https://docs.getgateman.com/canonical-client-node/), [Python](https://docs.getgateman.com/canonical-client-python/), and [Go](https://docs.getgateman.com/canonical-client-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:

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

Response when the test value is configured:

```json
{
  "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](https://docs.getgateman.com/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.

## Related references

- [Gateman Contract v1](https://docs.getgateman.com/contract-v1/)
- [Authentication and signing](https://docs.getgateman.com/authentication/)
- [Canonical PHP client](https://docs.getgateman.com/canonical-client-php/)
- [Canonical Node.js client](https://docs.getgateman.com/canonical-client-node/)
- [Canonical Python client](https://docs.getgateman.com/canonical-client-python/)
- [Canonical Go client](https://docs.getgateman.com/canonical-client-go/)