API reference

Alpacon provides a RESTful API to control and manage the states of servers. The root path for the API is /api/.

API endpoint#

Your workspace has a dedicated API endpoint:

https://<workspace>.<region>.alpacon.io/api/

Where:

• <workspace>: Your workspace slug
• <region>: Your workspace region (assigned at creation)

Example: https://mycompany.us1.alpacon.io

All API examples in this documentation use https://your-workspace.us1.alpacon.io as a placeholder. Replace it with your actual workspace endpoint.

Authentication#

Send a token in the Authorization header. Both kinds of token use the same format:

Authorization: token="alpst-xxxxxxxxxxxxxxxxxx"

• The keyword is lowercase token, then = and the key. The quotes are optional: token=alpst-... works too. Authorization: Bearer alpst-... is not accepted for either kind of token.
• Commands run inside a work session or through a service token.
• Use a service token for automated command execution and file transfers.
• Managing personal API tokens needs a signed-in session, not a token. See API tokens.

Some management routes require a signed-in session. Routes marked session-only refuse alpat- and alpst- keys. Follow Automate with a service token for setup with the CLI and web console. A service token created from the CLI always waits for approval in the web console. Each API page lists its accepted authentication methods.

When a credential is refused, the response is 401 with one of these codes:

Approve and reject on both the work-session routes and the approvals API instead return 400 auth_mfa_required without source when fresh MFA confirmation is missing. See Work sessions.

If Alpacon can’t check the credential at that moment, the response is 503 with auth_verification_unavailable. Retry the request; the credential was not refused.

Global information#

HTTP methods#

For more details, see the MDN HTTP methods reference.

URL structures#

We have the following API structures.

• List or create: /api/<collection>/<resource>/
• Retrieve, update, or delete: /api/<collection>/<resource>/<id>/
• Extra actions: /api/<collection>/<resource>/<id>/<action>/

For example, GET /api/iam/users/a540bf0f-8b37-4f03-8546-dd71c6b03329/ retrieves a user’s state.

Please note that all urls end with /.

Pagination#

Most list endpoints return one page at a time. The work-session timeline and records use cursor pagination with their own response shapes and limits.

For page-number pagination:

{
  "count": 85,
  "current": 1,
  "next": 2,
  "previous": null,
  "last": 6,
  "results": []
}

count is the total number of results, current the page you are on and last the final page. next and previous are page numbers, not URLs, and are null at either end. To read every result, request page=next until next is null. A page past last returns 404 with api_not_found.

Status codes#

Success codes:

Approval does not always mean 202. Work-session creation returns 201 with status: "pending" when approval is needed; poll the session to learn the outcome.

Error codes:

For the full list of HTTP status codes, see the MDN HTTP status reference.

Error messages#

Every error response carries a machine-readable code. The one exception is a 405 for a method the endpoint doesn’t support, which carries {"detail": "..."}. A 400 Bad Request additionally carries field_errors when Alpacon can pin the problem to a field—or to the request as a whole, under the non_field_errors key inside field_errors.

For example, when you are changing a user’s password, if the new password does not pass server-side validation, you will see a response like this. The field name, new_password, is used as the key inside field_errors. Build your integration against code, not message—message is often a generic string like “Invalid input.” and isn’t guaranteed to stay in English.

HTTP 400 Bad Request
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
  "code": "password_too_short",
  "field_errors": {
    "new_password": [
      {
        "code": "password_too_short",
        "message": "Invalid input."
      }
    ]
  }
}

field_errors maps each field to a list of {code, message} entries—a field can carry more than one entry when more than one check on it fails.

An error that isn’t about one specific field—for example, an object-level rule that depends on more than one value in the request—is filed under the non_field_errors key inside field_errors instead of a field name:

{
  "code": "approval_superuser_approve_required",
  "field_errors": {
    "non_field_errors": [
      {
        "code": "approval_superuser_approve_required",
        "message": "Invalid input."
      }
    ]
  }
}

Not every 400 carries field_errors. A validation failure raised without a specific field—for example, deleting the only remaining owner of a group—carries only the top-level code:

{
  "code": "user_unique_group_owner"
}

A few codes can come from any endpoint:

Application role validation errors#

These Application role grant and removal errors return 400. See Let an application manage one alert rule for the console steps.

Rate limits#

Each service token may make 1,000 requests an hour unless its own rate limit says otherwise; an administrator can set a different limit per token, as a count per second, minute, hour or day. Personal API tokens and signed-in sessions have no general limit, though a few endpoints have their own.

Over the limit, the response is 429 with a Retry-After header, the number of seconds to wait:

HTTP 429 Too Many Requests
Retry-After: 120

{
  "code": "api_rate_limited",
  "gate": "rate"
}

Wait for Retry-After before retrying. A pipeline that hits the limit often needs a higher limit on its token, not faster retries.

Refusals#

A 402, 403, 405, or 429 response that already carries a code may additionally carry fields that explain why the request was refused:

• gate: the class of control that refused the request.
• missing: the class of prerequisite that would have let the request through—or, for a token-scope refusal only, the literal scope string the credential lacks.
• hint: one English statement of at most two sentences, for a person to read. It says what you can do yourself, or what is missing and where the state of an existing request can be read.

gate and missing are optional and appear only where the server recorded them at the moment of refusal; treat their absence like any other field you don’t recognize and ignore it. hint is a string of at most 256 bytes with no control characters. It may appear on an authenticated refusal when the server has a matching hint for the code and gate. Print it as it is and never parse it: build your logic on code, gate and missing. Each code’s hint is quoted in Refusal codes. None of these fields is ever present on a 401. A 401 carries its code; a 401 auth_mfa_required also carries source, naming the MFA check it needs. Approve and reject on both the work-session routes and the approvals API use 400 auth_mfa_required without source.

gate values:

missing values:

Example—role refusal:

{
  "code": "rbac_permission_required",
  "gate": "role",
  "missing": "role",
  "hint": "Your roles do not allow this action; it needs a role that covers it."
}

Example—token scope missing:

{
  "code": "api_token_scope_missing",
  "gate": "token_scope",
  "missing": "scope:server:update"
}

gate, missing and hint never carry a rule’s contents, another principal’s identity, or a path to where the missing thing could be requested. gate and missing name only the class of control and the class of prerequisite, and hint speaks only of what is missing and what you can do within your own access. Treat any field on this envelope you don’t recognize as informational and safe to ignore.

Plan-limit refusals#

A 402 with gate: "plan" that refuses a resource limit, rather than a feature your plan doesn’t include at all, also carries an axis naming which limit was hit:

server, user, and application are count limits: the body also carries next, a relative API path to the workspace’s plan and limits. That path answers a signed-in console session and refuses token authentication, so if you’re calling with a token, treat next as informational and check current usage in the console instead. A count limit has no reset: it lifts once you remove something or the plan changes.

websh, webftp, and websh-share are monthly limits: instead of next, the response carries a Retry-After header, the number of seconds until the usage period resets. On a plan that doesn’t include Websh sharing at all, a websh-share refusal has no reset to wait for and carries no Retry-After. workspace is a rule on your account, the one Free workspace you can belong to, rather than a limit inside a workspace, so it carries neither next nor Retry-After.

The body never carries your current usage or the limit’s numeric value. Read those from the path in next, or from the plan and usage details in the console.

Example—count limit (server):

HTTP 402 Payment Required

{
  "code": "server_limit_exceeded",
  "gate": "plan",
  "axis": "server",
  "next": "/api/workspaces/workspaces/<workspace_id>/entitlements/"
}

Example—monthly limit (websh):

HTTP 402 Payment Required
Retry-After: 864000

864000 is an illustrative value (10 days); each response carries the seconds left in your own usage period.

{
  "code": "websh_limit_exceeded",
  "gate": "plan",
  "axis": "websh"
}

A 402 with gate: "plan" and no axis is a feature lock: your plan doesn’t include the feature at any usage, and no amount of waiting or removing lifts it.

{
  "code": "workspace_enterprise_plan_required",
  "gate": "plan"
}

Refusal codes#

At 402, 403, 405 and 429, every code below answers with a refusal body: plan refusals at 402, rate refusals at 429, workspace_put_info_disabled and command_acl_moved at 405, and the rest at 403. Some of these codes also answer at another status, where the body carries no refusal fields and no hint: auth_mfa_required at 400 and 401, api_not_for_alpacon, permission_denied and user_no_permission at 400, and workspace_unclaimed and workspace_not_unclaimed at 409. The meaning names the gate and missing a refusal carries, when it carries them.

Each entry under “What to do” opens with the code’s hint, word for word. When a code can be refused at more than one gate, the entry has one hint per gate, each after a label such as server_reach gate. The rest of the entry says where to make the change. Codes for a refused sudo command are in PAM and sudo issues.

For access decisions and recovery by action, see Related error codes.

Roles and permissions#

Tokens and credentials#

MFA checks#

Approvals and work sessions#

Console-only actions#

Methods refused with 405#

Workspace state#

Plan limits#

These answer 402 with gate: "plan". See plan-limit refusals for axis, next and Retry-After.

Rate-limit refusals#

These answer 429 with gate: "rate". See rate limits for a service token’s request limit.

Automate with a service token#

Use alpacon-cli 1.14.2 or later, with Bash, curl and jq installed. Sign in with alpacon login as a Superuser or an admin, selecting the same workspace as ALPACON_URL below. The alpacon api requests use that signed-in session and ask for MFA when needed. They print the response body to stdout; HTTP errors also print HTTP <code> to stderr and exit with code 1.

Steps 3, 5b, 6 and the self-hosted part of step 7 need a signed-in session. Steps 1, 2 and 4 also accept your own personal API token with the matching scopes, but no service token. Use your signed-in CLI session for all of those requests in this guide. A service token created from the CLI always waits for approval in the web console. Only the web console can approve it in step 5a; step 7 on Cloud also uses the console.

Set your workspace URL and the ID of one connected, commissioned Linux server running a current agent. Fill the remaining variables as you follow the steps. Response examples show only the relevant fields, with illustrative IDs and timestamps.

alpacon login
ALPACON_URL='https://your-workspace.us1.alpacon.io'
SERVICE_TOKEN=''
APP_ID=''
ROLE_ID=''
TOKEN_ID=''
APPROVAL_REQUEST_ID=''
SERVER_ID=''
COMMAND_ID=''
read -r -p 'Connected server ID: ' SERVER_ID

1. Create the application#

Create an application named CI pipeline with service type ci_cd before configuring its server account:

alpacon api -X POST /api/iam/applications/ \
  -f 'name=CI pipeline' -f service_type=ci_cd

Expected: 201 Created.

{"id":"<application-id>","name":"CI pipeline","service_type":"ci_cd","username":null,"shell":"/usr/sbin/nologin","provisioning_enabled":false,"auto_provisioning":false}

Save the application’s id:

read -r -p 'Application ID: ' APP_ID

2. Set the application’s server account#

Set the application’s username to ci-deploy and enable provisioning. Choose a username that does not match an existing server account or group. The first command creates the account on a Linux server running a current agent:

alpacon api -X PATCH "/api/iam/applications/$APP_ID/" \
  -f username=ci-deploy -F provisioning_enabled=true

Expected: 200 OK, with the updated application:

{"id":"<application-id>","username":"ci-deploy","provisioning_enabled":true}

An existing account or group name returns 400 approval_superuser_approve_required; complete that approval before continuing. To bind an existing server account instead, see the application’s server account binding API.

3. Grant the application a global role#

Grant the application the built-in operator role globally, without restricting the grant to a resource. This role includes command:create and command:read. You must be able to update the application and grant the role’s permissions. The token’s scopes must fit the application’s global role.

3a. Find the role:

alpacon api -X GET /api/rbac/roles/ -f name=operator

Expected: 200 OK, with results containing the role:

{"results":[{"id":"<role-id>","name":"operator"}]}

Save its id as ROLE_ID:

read -r -p 'Operator role ID: ' ROLE_ID

3b. Grant the role: omit content_type and object_id. Granting a role requires a fresh MFA check. Complete the prompt opened by alpacon api; without a fresh check, the API returns 401 auth_mfa_required with source: "rbac_binding".

alpacon api -X POST /api/rbac/application-roles/ \
  -f "application=$APP_ID" -f "role=$ROLE_ID"

Expected: 201 Created.

{"id":"<grant-id>","application":{"id":"<application-id>","name":"CI pipeline"},"role":{"id":"<role-id>","name":"operator"},"content_type":null,"object_id":null}

4. Create the service token#

Create a service token named ci-deploy with command:create and command:read. Set a future expiration and enter the justification Run deployment checks from CI. The example expiration below must still be in the future when you use it:

alpacon api -X POST /api/auth/service-tokens/tokens/ \
  -f name=ci-deploy -f "application=$APP_ID" \
  -f 'scopes[]=command:create' -f 'scopes[]=command:read' \
  -f expires_at=2027-01-01T00:00:00Z \
  -f 'justification=Run deployment checks from CI'

Command scopes are medium risk and require a nonempty justification. Creation always returns 202 Accepted with a pending token for these scopes:

{"id":"<token-id>","name":"ci-deploy","application":{"id":"<application-id>","name":"CI pipeline","service_type":"ci_cd","username":"ci-deploy"},"key":"alpst-…","enabled":false,"activation_state":"pending","scopes":["command:create","command:read"],"expires_at":"2027-01-01T00:00:00Z","rotation_policy":"90d","status":"pending_approval","risk_level":"medium","approval_request_id":"<approval-request-id>"}

Save key securely now; later GET responses do not return it. Save the token and approval request IDs too. The pending key cannot authenticate yet.

read -r -p 'Service token ID: ' TOKEN_ID
read -r -p 'Approval request ID: ' APPROVAL_REQUEST_ID
read -r -s -p 'Service token key: ' SERVICE_TOKEN
printf '\n'

5. Approve the token and confirm it is active#

5a. Approve in the web console: only the web console can approve the token. Open https://<workspace-console>/<workspace>/approvals?selected=$APPROVAL_REQUEST_ID, replacing the console host and workspace placeholders with yours and $APPROVAL_REQUEST_ID with the ID saved in step 4. Or open Pending approvals and select the Create a service token row for this request. A Superuser or an approver for that request approves it. The requester may approve their own request unless an approval policy forbids it. Complete a fresh MFA check if requested. If the policy requires more approvals, wait for approval to complete.

5b. Confirm it is active: return to the CLI and read the token:

alpacon api -X GET "/api/auth/service-tokens/tokens/$TOKEN_ID/"

Expected: 200 OK with scope_usage and no key:

{"id":"<token-id>","activation_state":"active","enabled":true,"scopes":["command:create","command:read"]}

6. Allow the server#

After approval, allow the server identified by SERVER_ID in the token’s access rules. ACL writes accept only an approved, enabled token target. A pending or disabled target returns 400 does_not_exist on service_token.

alpacon api -X POST /api/security/server-acl/ \
  -f "service_token=$TOKEN_ID" -f "server=$SERVER_ID"

Expected: 201 Created.

{"id":"<server-acl-id>","token":null,"service_token":"<token-id>","token_name":"ci-deploy","server":{"id":"<server-id>","name":"deploy-server","is_connected":true,"is_deleted":false}}

7. Allow the command#

On Alpacon Cloud, open the token’s page in the web console and select its Access rules tab (?tab=acl). Under Pre-approved commands, choose Add to open Add command. If the console says this list is managed by Command ACL admins, ask an admin for access. If the browser asks you to connect, choose Connect; this connection may be needed once.

In the dialog, set Command to df -h. Set Run as to * for any account, or enter ci-deploy. Set Group if you need a group restriction. Select servers under Servers to limit the rule to them; with no server selected, it applies to every server the token reaches. Confirm that the command appears in the list. Command ACL rows returned by the ACL API on Cloud do not decide which token commands run; writes to that API return 405 command_acl_moved.

On a self-hosted deployment, allow df -h in the token’s command access rules:

alpacon api -X POST /api/security/command-acl/ \
  -f "service_token=$TOKEN_ID" -f 'command=df -h'

Expected on a self-hosted deployment: 201 Created.

{"id":"<command-acl-id>","token":null,"service_token":"<token-id>","token_name":"ci-deploy","command":"df -h","username":"","groupname":""}

The empty username and groupname add no account restriction to this rule. The command still runs as the application’s account from step 2.

8. Run the command with the token#

Use the approved token to call the commands API. No work session is required. Omit username and groupname so the command runs as the application’s account. Send one connected, commissioned server; if the server is disconnected, the request returns 400 server_not_connected; if it is not commissioned, the request returns 400 server_not_commissioned.

A 400 does_not_exist error on server means the server is missing from the token’s server access rules or does not exist; check SERVER_ID and return to step 6. A 400 application_system_user_not_found error means the application’s account could not be provisioned: use a Linux server running a current agent, as required in step 2.

COMMAND_RESPONSE=$(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\":\"$SERVER_ID\",\"line\":\"df -h\",\"purpose\":\"Check disk space before deploying\"}")
printf '%s\n' "$COMMAND_RESPONSE" | jq .
COMMAND_ID=$(printf '%s' "$COMMAND_RESPONSE" | jq -er '.[0].id')

Expected: 201 Created, with a one-item list. The first command after enabling provisioning waits behind account setup: status is queued and run_after identifies the earlier command. The initial status may differ as the command progresses; accepting it does not mean it has finished.

[{"id":"<command-id>","line":"df -h","purpose":"Check disk space before deploying","username":"ci-deploy","groupname":"ci-deploy","status":"queued","run_after":["<account-setup-command-id>"],"request_channel":"service_token","work_session":null,"service_token":"<token-id>","application":"<application-id>"}]

9. Poll and read the command record#

Poll the detail route until status is completed, rejected or denied:

HEADERS=$(mktemp)
BODY=$(mktemp)
while true; do
  HTTP_STATUS=$(curl --silent --show-error \
    --dump-header "$HEADERS" --output "$BODY" --write-out '%{http_code}' \
    "$ALPACON_URL/api/events/commands/$COMMAND_ID/" \
    -H "Authorization: token=\"$SERVICE_TOKEN\"") || break
  if [ "$HTTP_STATUS" = 429 ]; then
    RETRY_AFTER=$(awk 'tolower($1) == "retry-after:" { print $2 + 0 }' "$HEADERS")
    sleep "${RETRY_AFTER:-60}"
    continue
  fi
  if [ "$HTTP_STATUS" != 200 ]; then
    cat "$BODY"
    break
  fi
  COMMAND_RECORD=$(cat "$BODY")
  printf '%s\n' "$COMMAND_RECORD" | jq '{status, success, exit_code, result, elapsed_time, handled_at, rejection_cause, rejection_gate, rejected_at}'
  COMMAND_STATUS=$(printf '%s' "$COMMAND_RECORD" | jq -er '.status') || break
  case "$COMMAND_STATUS" in
    completed|rejected|denied) break ;;
  esac
  sleep 5
done
rm -f "$HEADERS" "$BODY"

The loop polls every 5 seconds (720 requests an hour, under the default 1000/hour limit); on a 429, it waits the number of seconds in Retry-After and continues, so a command that waits a long time for approval still reaches its final record.

awaiting_approval waits for an approver in the web console; the loop keeps polling.

Expected for each GET: 200 OK. While the command runs, status may be delivered or running and handled_at is null. A completed response includes:

{"id":"<command-id>","status":"completed","success":true,"exit_code":0,"result":"<command output>","elapsed_time":0.12,"acked_at":null,"handled_at":"2026-10-24T12:00:00Z","verification_status":"approved","risk_level":"LOW"}

Read success first, then exit_code, result, elapsed_time and handled_at. acked_at can be null even when the command is completed. A stuck command that times out also ends as completed, but with success: false, exit_code: null and a timeout message in result.

For status: "rejected", inspect rejection_cause, rejection_gate and rejected_at; for status: "denied", inspect result. The separate denied field is available only on the list route, not this detail response. See Command status for waiting and running states.

The same detail response is the command record: it includes delivered_at, acked_at, handled_at, verification_status, risk_level, service_token, service_token_name, application, application_name and request_channel. See Get command for the fields.

Alpacon features#

Following documents describe the details about each collection of API.