Get started with the REST API

Follow these steps to enable Firezone's REST API and generate the credentials you need to authenticate your requests. For details on the available endpoints, see the REST API reference.

Request API access

Open the Settings → API Clients section of the admin portal and request access. This sends a notification to the Firezone team to enable the API for your account.

Create an API client and token

Once the API is enabled for your account:

1. Generate an API Client from the same page where you requested access.
2. Generate an API Token for that client.
3. 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:

export FZ_API="https://rest-api.firezone.dev"
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.