---
title: "Automate with the REST API"
description: "Connect a scoped service token to the Alpacon REST API and list servers. Read a paginated result, then handle token expiry or a refusal in your workflow."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# Automate with the REST API

Use a service token for automation that acts as an application. This example reads the servers visible to the token. For the full request and response contract, see the [servers API](/reference/api/servers/servers/).

## Choose an identity and token

Create an [application and service token](/use/iam/applications/service-tokens/) with the `server:read` scope. Give it access only to the servers this workflow needs. The [scope reference](/reference/scopes/) lists other actions. A personal API token acts as its owner and is suitable for that person's own API tasks; it cannot be issued with command execution or file transfer scopes.

Store the service token securely. If it is pending approval, wait until it is active before making requests. A token's expiry and its IP or time restrictions can also refuse a request.

## Authenticate

Use the URL of your workspace and send the token in the `Authorization` header. Replace the placeholders with your own values. The keyword is lowercase `token`; a `Bearer` header is not accepted.

```bash
export ALPACON_URL='https://your-workspace.us1.alpacon.io'
read -r -s -p 'Service token: ' SERVICE_TOKEN
printf '\n'
curl --fail-with-body --silent --show-error \
  "$ALPACON_URL/api/servers/servers/?page_size=15" \
  -H "Authorization: token=\"$SERVICE_TOKEN\""
```

## Read the result

The response contains `results` and page numbers such as `next`. Request each `next` page until it is `null`; a response with `next: null` is the last page. The [API overview](/reference/api/#pagination) defines pagination and status codes. Use the [server filters](/reference/api/servers/servers/#list-servers) when the workflow needs a subset.

For a command or file transfer, use a [service token with the required scopes and access rules](/use/iam/applications/service-tokens/) and follow the exact [commands API](/reference/api/commands/) or file API contract. The token's server reach and command or file rules still apply.

## Handle expiry and refusals

On `401`, check whether the token is active, unexpired, and within its allowed IP and time window. A `403` can mean the token lacks a scope or another required access rule; inspect `code`, `gate`, and `missing` when present. For a rate refusal, honor `Retry-After`. Build branches on the structured fields, not the human-readable `message` or `hint`. The [API refusal reference](/reference/api/#refusals) explains each field.

## Run a command through the API

For command automation, create an application account such as `ci-deploy`, issue a service token with the required command scopes, and allow the target server and exact command in its access rules. Prepare the deployment directory for that account. This example uses the [commands endpoint](/reference/api/commands/):

```bash
curl --fail-with-body --silent --show-error \
  -X POST "$ALPACON_URL/api/events/commands/" \
  -H "Authorization: token=\"$SERVICE_TOKEN\"" \
  -H 'Content-Type: application/json' \
  -d '{"server":"7e3984de-49ab-4cc6-bcdf-21fbd35858b8","line":"deploy","username":"ci-deploy","purpose":"Run the approved deployment"}'
```

A command may wait for approval or provisioning after the API accepts it. Read the command record to learn its final status. The [service-token command guide](/use/iam/applications/service-tokens/command-patterns/) explains how a rule matches the full line.

The CLI can run the same approved workflow:

```bash
alpacon exec ci-deploy@production "cd /app && git pull && npm install && pm2 restart"
for server in web1 web2 web3; do
  alpacon exec "ci-deploy@$server" "sudo systemctl restart nginx"
done
```

The second example needs a rule that matches the full `sudo systemctl restart nginx` line. On Alpacon Cloud, when workspace sudo settings permit it, **Service token execution** allows service-token sudo below **Critical** by default unless a stricter workspace rule applies. The default self-hosted setup refuses service-token sudo. See [Access rules](/reference/access-rules/) for the exact decision conditions.

Source: https://docs.alpacax.com/integrate/rest-api/
