# Using Gateman with coding agents

Gateman lets an application use supported provider capabilities without
giving a coding agent the underlying provider credentials. The agent works
against Gateman's authenticated, application-scoped interface while Gateman
keeps configured provider credentials inside its protected storage.

Gateman is not a universal provider proxy or an IAM replacement. Each
capability has its own routes, payload, provider behavior, and limits. Provider
permissions remain authoritative, and Gateman only authorizes capabilities
enabled for the application.

## What each participant does

The developer controls the application and its authorization:

- Create or select the Gateman application.
- Enable the required capabilities.
- Configure the provider credentials and settings in the Gateman console.
- Obtain and protect the application's signing material.
- Give the coding agent the appropriate setup instructions.
- Control deployment, environment selection, and production authorization.

The coding agent implements the application integration:

- Select the Official client for the application's language.
- Configure the client from application-controlled runtime configuration.
- Authenticate and retrieve the current application context.
- Read the Capability Reference for the enabled operation.
- Implement, test, and handle the documented response and failure behavior.

The developer decides the application's architecture, provider choices, and
whether existing application code is retained, removed, or replaced. Gateman
defines the authorized capability contracts and their provider-specific
request, response, and failure behavior; it does not prescribe the
application's internal design.

Gateman authenticates application requests, enforces application capability
scopes, uses configured provider credentials for supported operations, and
returns the current application integration context. Gateman does not create
or authorize application credentials on behalf of an agent.

Application signing credentials are separate from provider credentials. The
agent must not receive provider keys merely because it is implementing a
provider-backed feature, and the application must still protect its own
HMAC secret or Ed25519 private key.

## End-to-end workflow

1. Configure the Gateman application in the console.
2. Enable the capability the application needs.
3. Configure the relevant provider credentials in Gateman.
4. Obtain the console-generated bootstrap instructions.
5. Install the application's language-specific [Official
   client](https://docs.getgateman.com/canonical-client-php/).
6. Load the Gateman application configuration into the server-side runtime.
7. Authenticate with Contract v1 and request `POST /client/get`.
8. Identify the enabled capability, its required scope, routes, and linked
   documentation.
9. Follow the selected [Capability Reference](https://docs.getgateman.com/capabilities/email.send/).
10. Implement and test the operation using the client's generic request method.
11. Optionally copy stable, non-secret guidance into the project's
    [`AGENTS.md` integration](https://docs.getgateman.com/agents-md-integration/).

The bootstrap prompt supplies connection setup. The authenticated `/client/get`
response supplies current application-specific capability context. See
[Bootstrap context](https://docs.getgateman.com/bootstrap-context/) for that
handoff.

## Different capability models

Gateman capabilities do not all operate in the same way:

- A provider-native relay sends a bounded request through Gateman, such as the
  supported AWS or Cloudflare administrative relays. The provider's own
  permissions still decide whether the operation is allowed.
- S3 and R2 presigning returns a signed request. Object bytes transfer directly
  between the application and the storage provider; Gateman does not proxy the
  object body.
- Email and SMS capabilities submit provider-native messages or capture them
  according to the documented application environment behavior.
- Provisioning capabilities perform a specific setup action needed by a
  supported capability. They are not general infrastructure management.
- Explicit credential-retrieval capabilities can return an authorized value,
  but only when their separate scope and provider retrieval settings allow it.
  Credential retrieval is not the normal implementation path for a supported
  relay or presigning capability.

Read the selected Capability Reference before choosing an integration model.

## A practical instruction for a coding agent

A developer can provide an agent with an instruction such as:

```text
Use the Gateman application configuration already supplied to this server-side
application. Use the Official client for this language, authenticate with
Contract v1, and call POST /client/get. Implement the developer's requested
functionality using the capabilities authorized for this application and
relevant to that task. Read each selected capability's linked Capability
Reference and preserve its provider-native request, error, retry, idempotency,
and environment rules. Do not expand the task to implement every authorized
capability.
Do not request or add provider credentials. Keep Gateman signing material in
server-side runtime configuration and out of source, logs, prompts, and browser
code.
```

The exact application ID, base URL, authentication mode, and signing material
belong in the application's protected setup and runtime configuration. They
are not supplied by this generic project instruction.

## Boundaries and first-request checks

An absent capability in `/client/get` means the application is not currently
authorized for it. A configured provider credential name does not prove that
the provider is ready, and an enabled capability does not make every provider
or operation available. Use the documented route and payload; do not invent a
universal helper or provider operation.

For authentication and response handling, see [Authentication](https://docs.getgateman.com/authentication/),
[Contract v1](https://docs.getgateman.com/contract-v1/), and [Errors and
responses](https://docs.getgateman.com/errors-and-responses/). Use [Environments](https://docs.getgateman.com/environments/)
for application environment behavior.

## Related references

- [Bootstrap context](https://docs.getgateman.com/bootstrap-context/)
- [AGENTS.md integration](https://docs.getgateman.com/agents-md-integration/)
- [Contract v1](https://docs.getgateman.com/contract-v1/)
- [Authentication](https://docs.getgateman.com/authentication/)
- [Errors and responses](https://docs.getgateman.com/errors-and-responses/)
- [Environments](https://docs.getgateman.com/environments/)
- [Official PHP client](https://docs.getgateman.com/canonical-client-php/)
- [Official Node.js client](https://docs.getgateman.com/canonical-client-node/)
- [Official Python client](https://docs.getgateman.com/canonical-client-python/)
- [Official Go client](https://docs.getgateman.com/canonical-client-go/)
- [Capability References](https://docs.getgateman.com/capabilities/email.send/)
- [Security overview](https://docs.getgateman.com/security-overview/)