Gateman
Documentation/Getting started with an application

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/.

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/.

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.
  1. The capabilities this application will use.
  2. 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:

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 for the provider-specific setup, request, environment, and response rules.

5. Install an Official client

Gateman provides four equally official clients:

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.

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:

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 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.
  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