Get started with the REST API

Follow these steps to generate an API token and authenticate your requests. For details on the available endpoints, see the REST API reference.

Create an API token

Open the Settings → API Tokens section of the admin portal, then:

1. Generate an API Token.
2. Use the token to authenticate your requests.

Build your first deployment with the API

This walkthrough mirrors the Quickstart guide, but drives every step through the REST API instead of the admin portal: create a Site, provision a Gateway, add a Resource, then grant a Group access with a Policy. By the end you'll have a working deployment that users can connect to with a Client.

The examples use curl and jq. Every request is authenticated with your API token as a bearer token, and responses are wrapped in a top-level data object. Start by exporting the API base URL and your token. The base URL depends on the region of your account: https://rest-api.firezone.dev for Firezone Cloud US and https://eu.rest-api.firezone.dev for Firezone Cloud EU. An API token only works with the API of its own region.

export FZ_API="https://rest-api.firezone.dev" # https://eu.rest-api.firezone.dev for EU accounts
export FZ_TOKEN="<your-api-token>"

1. Create a Site

A Site is where Gateways and Resources live. Create one and capture its id for the steps that follow:

SITE_ID=$(curl -s -X POST "$FZ_API/sites" \
  -H "Authorization: Bearer $FZ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "site": { "name": "Production" } }' | jq -r '.data.id')

2. Provision a Gateway

Mint a Gateway token for the Site, then use it to deploy a Gateway:

GATEWAY_TOKEN=$(curl -s -X POST "$FZ_API/sites/$SITE_ID/gateway_tokens" \
  -H "Authorization: Bearer $FZ_TOKEN" | jq -r '.data.token')

Pass the returned value as FIREZONE_TOKEN to any of the Deploy Gateways methods — for example, with Docker:

docker run -d --name=firezone-gateway --cap-add=NET_ADMIN \
  --device="/dev/net/tun:/dev/net/tun" \
  --env FIREZONE_TOKEN="$GATEWAY_TOKEN" \
  --env FIREZONE_ID="$(cat /proc/sys/kernel/random/uuid)" \
  ghcr.io/firezone/gateway:1

3. Add a Resource

Create a Resource in the Site. The type is one of dns, ip, or cidr; filters are optional port/protocol restrictions:

RESOURCE_ID=$(curl -s -X POST "$FZ_API/sites/$SITE_ID/resources" \
  -H "Authorization: Bearer $FZ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": {
      "name": "Prod DB",
      "type": "ip",
      "address": "10.0.0.10",
      "address_description": "Production database",
      "filters": [{ "protocol": "tcp", "ports": ["5432"] }]
    }
  }' | jq -r '.data.id')

4. Create a Group

Access is granted to Groups, not individual actors. Create one to grant access to:

GROUP_ID=$(curl -s -X POST "$FZ_API/groups" \
  -H "Authorization: Bearer $FZ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "group": { "name": "Engineering" } }' | jq -r '.data.id')

5. Create a Policy

Access is default-deny, so grant the Group access to the Resource with a Policy:

curl -s -X POST "$FZ_API/policies" \
  -H "Authorization: Bearer $FZ_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{ \"policy\": { \"group_id\": \"$GROUP_ID\", \"resource_id\": \"$RESOURCE_ID\" } }"

6. Verify

Confirm the Gateway came online in the Site:

curl -s "$FZ_API/sites/$SITE_ID/gateways" \
  -H "Authorization: Bearer $FZ_TOKEN" | jq '.data[] | { name, online }'

Add the actors you want to the Engineering Group, then have them install a Client and sign in — they'll have access to the Prod DB Resource.

Need help? See all support options.