Copy page

CLI

Walkthrough: from an empty folder to a customer's first call

This page follows one project from an empty folder to a customer calling the protected API with their own key. Every step is a command you run, or something your customer does in the portal.

Code
 you:       init ─► add identity ─► add gateway ─► add plans ─► project create ─► deploy
 customer:  open the portal ─► create an account ─► confirm the email ─► sign in
            ─► subscribe to the Free plan ─► create an API key ─► call the API with the key
 you:       teardown (when it was a test)

What you need

• Node.js 20 or later
• An APItoGo account, signed in for the CLI (see Install the CLI)
• An API that is reachable over HTTPS. This walkthrough uses https://httpbin.org as a stand-in.

1. Create the project folder

Code
apitogo init my-portal --yes --name my-portal
cd my-portal

init creates a config version 2 project with a portal, and installs the CLI into it. The commands below use the installed CLI through apitogo.

2. Add the services

Code
apitogo add identity
apitogo add gateway --origin proxy --url https://httpbin.org --auth identity --create-spec
apitogo add plans --template free

Service	What it gives you
identity	Sign-up, sign-in, email confirmation and password reset for your customers
gateway	The address your customers call. It forwards to your API and applies the plan's limits
plans	The plan catalog, subscriptions, API keys and usage. The Free template limits calls (see below)

--create-spec writes a small OpenAPI file with one GET /health operation, so the gateway has something to expose. For a real API, point gateway.specs at your own OpenAPI file instead.

The Free template in plans.json allows 60 calls per minute and 1000 calls per 30 days. Change the numbers in plans.json and deploy again to change the limits.

With plans in the project, customers call the gateway with their API key alone. Their login token is not needed. To require both, set gateway.policies.access yourself. A value you set is never replaced.

3. Create the platform project and deploy

Code
apitogo project create
apitogo deploy

deploy runs the services in a fixed order and prints what it did:

Code
identity: deployed (https://id.apitogo.com/<project>)
gateway:  deployed (https://free-api.apitogo.com/p<project>/), 1 operation(s)
  browser access updated for the portal address
plans:    deployed (https://portal.<your-portal-address>)
portal:   deployed to production (https://<your-portal-address>)

The portal's address is only known once the portal is published. The gateway only accepts browser calls from addresses it knows, so deploy sends the gateway its list again after the portal. One deploy is enough: you do not need to run it twice.

Running deploy again changes only what changed. Use apitogo status to see each service and apitogo plan to see what the next deploy would do.

4. The customer's side

Open the portal address and follow the steps your customer follows:

1. Choose Log in. The portal sends the customer to your project's sign-in page.

2. Choose Create an account, enter an email address and a password, and confirm the email. The link in the email works for 24 hours.

3. Sign in. The customer lands back in your portal.

4. Open Plans and subscribe to Free.

5. Open API keys, create a key, and copy it.

6. Call the API with the key in the Ocp-Apim-Subscription-Key header:

   Code
   curl -i -H "Ocp-Apim-Subscription-Key: <the key>" \
     https://free-api.apitogo.com/p<project>/health

What the gateway answers:

Request	Answer
A valid key	The answer of your API
No key, a wrong key, or a revoked key	401
More calls than the plan allows	429. A quota answer carries a Retry-After header

The customer sees their calls on the Usage page. See Your customers' account pages.

5. Sell a paid plan (optional)

Free plans need no payment. To charge your customers, the project needs two things: a Starter or Professional plan with APItoGo, and your own Stripe account. Your customers pay you, not APItoGo.

1. Create the project on a paid platform plan: apitogo project create --plan starter. This opens the platform's checkout for the hosting fee. A project that already exists on the Free plan cannot be moved: create a new one. See Selling paid plans needs Starter or Professional.
2. Give a plan a price in plans.json: "priceAmount": 49, "priceCurrency": "usd" and "billingInterval": "month". Its limits cannot be higher than your platform plan allows. Payments go through Stripe; nothing else in the config changes.
3. Deploy: apitogo deploy. Because a plan now has a price, deploy asks for your Stripe secret key (it starts with sk_test_ while you test) and stores it as the project secret STRIPE_API_KEY, so it stays out of your files. You can also store it beforehand with apitogo secrets set STRIPE_API_KEY. The output says whether Stripe is in test or live mode and prints your portal's webhook address.
4. In Stripe, add that address as a webhook endpoint with the events checkout.session.completed, customer.subscription.updated, customer.subscription.deleted and invoice.payment_failed. Copy the signing secret (it starts with whsec_), store it with apitogo secrets set STRIPE_WEBHOOK, add "plans": { "billing": { "webhookSecret": "secret:STRIPE_WEBHOOK" } } to apitogo.config.json, and deploy again. Until then a payment does not activate the plan, because the portal cannot confirm it came from Stripe.

While you use a test key, pay with Stripe's test cards. No real money moves. Never type a live key until you have tested the whole path.

6. Remove a test project

Code
apitogo teardown --yes

This deletes the platform project: the gateway, the identity and its users, the portal, its address and certificate, and the project's email domain. Your local files stay.

Things worth knowing

• One identity per project. A customer who signs up on one project cannot sign in to another.
• Sign-up needs a real email address. Confirmation and password-reset emails are sent to it. For tests, an address with a suffix such as you+test1@example.com usually reaches your own mailbox.
• Secrets stay out of the config. A value such as an origin key is written as secret:NAME and set with apitogo secrets.

Related

• Install the CLI
• CLI commands
• Protect an API with the gateway
• Your customers' account pages