# Getting started

The InfraNest API lets you automate the infrastructure you manage in InfraNest: DNS records, monitors,
maintenance windows, incidents and status pages. This guide takes you from no token to your first call in
about five minutes.

## Before you start

- An InfraNest account on a plan that includes the API.
- Your organization's ID. It's under **Settings → Organization** in the app, with a copy button. Or ask the API: `GET /api/organizations` lists every organization your token can reach. See the [FAQ](faq.md).
- A terminal with `curl`.

The API lives at `https://api.infranest.io/api`. Every request sends a token and asks for JSON.

There are two ways in. An **API token**, used in this guide, is for your own scripts and tools and acts as you. An
app that acts for other people — an integration, a hosted service — uses [OAuth](oauth.md): each person connects it
to their own account, and nobody copies a token.

## Create a token

1. In the app, open **My account → Developer** and choose **New token**.
2. Give it a name that says where it will be used, for example `ci-dns`.
3. Give it only what it needs. For this guide, tick **DNS → Read**.
4. Copy the token. It's shown once. Store it where your scripts read secrets, never in code.

A token works with your infrastructure, never with your account: tokens, members, billing and passwords stay in
the app. Some actions are not available to a token at all; see [Tokens and scopes](tokens-and-scopes.md). What
you do with a token is your responsibility, and it can cause costs at your providers; see
[Responsibility and costs](responsibility-and-costs.md).

## Make your first call

List the DNS zones in your organization. Replace `42` with your organization's ID.

```sh
curl https://api.infranest.io/api/organizations/42/dns-zones \
  -H "Authorization: Bearer $INFRANEST_TOKEN" \
  -H "Accept: application/json"
```

You get back the zones in that organization, each with an `id` you use to work with its records.

## When something goes wrong

Every error has the same shape and a stable `code`, with a `hint` saying what to do:

```json
{
  "code": "scope_missing",
  "message": "This API token does not have the dns.write scope.",
  "hint": "Create a token that includes the scope named in \"required\". Give each token only the scopes it needs.",
  "retryable": false,
  "required": "dns.write"
}
```

Write your scripts against `code`, never the message. The full list is in [Errors](errors.md).

## What next

- [Let's Encrypt with InfraNest DNS](recipes/acme-dns-01.md)
- [Install the server agent on many servers](agent/install-on-many-servers.md)
- [Every error code](errors.md)
- [Build an app people connect with OAuth](oauth.md)