# Getting started with an application

This guide takes you from creating a Gateman account to making your first
authenticated request from an application. Gateman does not require a
particular programming language, framework, hosting provider, or deployment
architecture.

## 1. Create your Gateman account

Open [https://getgateman.com/signup/](https://getgateman.com/signup/).

Signup offers a 14-day Standard trial and also allows direct subscription to
an available Standard or Premium plan. The trial is optional. Choose the
allowance and plan shown on the signup page; current prices, availability, and
included limits are authoritative there.

After registration, sign in at [https://getgateman.com/console/login/](https://getgateman.com/console/login/).

## 2. Create an application

Open **Apps** in the Gateman console and select **Create app**. The form asks
for:

1. An application name. This is a customer-facing label; Gateman generates
   the permanent App ID.
2. An authentication method:
   - **Ed25519**, the recommended method.
   - **HMAC**, for compatibility with applications that need it.
3. The capabilities this application will use.
4. Optional exact server IP addresses from which the application may connect.

Choose only the capabilities the application needs. A capability authorizes
its supported Gateman operations; it does not grant unrestricted access to the
underlying provider.

Application authentication is separate from console authentication. Your
console account and team membership control people using Gateman's management
console. The application uses its own App ID and signing credential when it
calls Gateman.

## 3. Save the one-time credential

After the application is created, Gateman shows its signing material once.

- For Ed25519, the private seed is shown once and Gateman stores the
  corresponding public key.
- For HMAC, the application secret is shown during setup and stored encrypted
  by Gateman for request verification. It is not shown again in the console.

The console provides a `.gateman` template as a supported setup starting
point. You may use it, or keep the same values in your existing secure
server-side application or deployment configuration. Official clients do not
automatically load `.gateman` files. In either case, do not commit signing
material, log it, expose it to browser code, or place it in a general
coding-agent prompt.

The template contains:

```text
APP_ENVIRONMENT=production
GM_APP=<your App ID>
GM_BASE_URL=https://getgateman.com
GM_PRIVATE_KEY=<your one-time Ed25519 seed>
```

HMAC applications use `GM_APP_SECRET` instead of `GM_PRIVATE_KEY`. Set
`APP_ENVIRONMENT` to `production`, `staging`, or `development` for the
application deployment. Gateman does not determine the application’s current
runtime environment.

## 4. Configure provider credentials in Gateman

Open the application in the console and configure the provider credentials
required by its selected capabilities. The exact requirements depend on the
provider and capability. For example, email, payment, storage, SMS, and
provider-relay capabilities use different provider configuration.

Some capabilities also require provider-native authorization or a supported
provisioning workflow. Gateman's application scope does not replace AWS IAM,
Stripe, Square, PayPal, Cloudflare, or other provider permissions.

Use the relevant [Capability Reference](https://docs.getgateman.com/capabilities/email.send/)
for the provider-specific setup, request, environment, and response rules.

## 5. Install an Official client

Gateman provides four equally official clients:

- [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/)
- [Go](https://docs.getgateman.com/canonical-client-go/)

Acquire the client during setup or deployment using the acquisition method in
its guide. Official clients provide the authenticated transport and signing
boundary.

You can also implement the transport directly using [Contract v1](https://docs.getgateman.com/contract-v1/).

## 6. Retrieve the current application context

Once the application has loaded its Gateman authentication configuration using
its chosen secure runtime mechanism and an Official client is available, call
the authenticated:

```text
POST /client/get
```

This request requires the `client:read` scope. It returns the application's
current authorized capability context, including scopes, capabilities, routes,
provider-configuration metadata, environment information, implementation
rules, and documentation references.

The response is the current application-specific context. If you later change
scopes, capabilities, or provider configuration, call `/client/get` again; do
not regenerate an old setup prompt as a substitute.

See [Bootstrap context](https://docs.getgateman.com/bootstrap-context/) for
further details about the context returned by `POST /client/get`.

## 7. Make the first capability request

To make the first capability request:

1. Select a capability authorized for the application.
2. Open that capability's linked [Capability Reference](https://docs.getgateman.com/capabilities/email.send/).
3. Construct the request using the documented route and payload.
4. Execute it through the chosen Official client's generic authenticated
   request method.
5. Handle the HTTP status, response body, and capability-specific errors
   according to the applicable contract.

For example, `email.send` is one capability with its own operation contract.
Do not assume that routes, payloads, responses, or limits are interchangeable
between capabilities or providers.

## Where to go next

- [Authentication and signing](https://docs.getgateman.com/authentication/)
- [Contract v1](https://docs.getgateman.com/contract-v1/)
- [Environments](https://docs.getgateman.com/environments/)
- [Operation Accounting](https://docs.getgateman.com/operation-accounting/)
- [Capability References](https://docs.getgateman.com/capabilities/email.send/)
- [Using Gateman with coding agents](https://docs.getgateman.com/using-gateman-with-coding-agents/)
- [Bootstrap context](https://docs.getgateman.com/bootstrap-context/)
- [Security overview](https://docs.getgateman.com/security-overview/)