Applications

Endpoint: /api/iam/applications/

An application is an identity for automation. Create one before issuing its service tokens. Each token’s scopes must fit the application’s global roles; grant the application a global role before creating the token.

Authentication and permissions#

Use a signed-in session or a personal API token. Service tokens cannot call this API. A personal token needs the matching application:create, application:read, application:update or application:delete scope.

Every authenticated member can list and read applications. Creating one needs application:create; changing or deleting one needs application:update or application:delete on that application. Admins hold these permissions, and the creator receives the application:maintainer role on the application. Writes return 403 workspace_suspended while the workspace is suspended.

The examples use a personal API token for a caller with the required roles and scopes.

List applications#

Request#

GET /api/iam/applications/

Query parameters#

Response#

200 OK, using integer pagination. This example shows selected application fields:

{
  "count": 1,
  "current": 1,
  "next": null,
  "previous": null,
  "last": 1,
  "results": [
    {
      "id": "9d2e4b71-0c3a-4f5e-8b6d-1a2c3e4f5a6b",
      "name": "CI pipeline",
      "description": "Deployment checks",
      "service_type": "ci_cd",
      "permissions": {"update": true, "delete": true}
    }
  ]
}

Example#

curl "https://your-workspace.us1.alpacon.io/api/iam/applications/?service_type=ci_cd" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""

Application fields#

For readers who are neither admins nor application owners, responses omit username, uid, shell, home_directory, provisioning_enabled and auto_provisioning. List responses omit shell and home_directory for everyone.

Create an application#

Request#

POST /api/iam/applications/

Send name and any optional fields from the table. Do not send username: it cannot be set at creation. Because provisioning requires a username, provisioning_enabled cannot be true in this request. Set the username and provisioning options afterward with PATCH.

Request body#

{
  "name": "CI pipeline",
  "description": "Deployment checks",
  "service_type": "ci_cd"
}

Response#

201 Created with the application fields. Creating an application beyond the workspace plan’s count limit returns 402 application_limit_exceeded, with axis: "application". The built-in alpacon application does not count toward that limit.

Example#

curl -X POST "https://your-workspace.us1.alpacon.io/api/iam/applications/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
  -H "Content-Type: application/json" \
  -d '{"name":"CI pipeline","description":"Deployment checks","service_type":"ci_cd"}'

Get an application#

GET /api/iam/applications/{id}/

id is the application UUID. Returns 200 with the application fields visible to you.

Update an application#

Request#

PATCH /api/iam/applications/{id}/
PUT /api/iam/applications/{id}/

Returns 200 with the updated application. id, created_by, timestamps and permissions are read-only.

Setting username binds matching server accounts that are not already linked to an identity. Changing it unbinds accounts automatically linked by the previous name. A name matching an existing server account or group can require approval: the request returns 400 approval_superuser_approve_required and creates an approval request.

Example#

curl -X PATCH "https://your-workspace.us1.alpacon.io/api/iam/applications/9d2e4b71-0c3a-4f5e-8b6d-1a2c3e4f5a6b/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
  -H "Content-Type: application/json" \
  -d '{"username":"ci-deploy","provisioning_enabled":true}'

Bind or unbind server accounts#

Request#

POST /api/iam/applications/{id}/system-users/
POST /api/iam/applications/{id}/system-users/unassign/

A Superuser or the application’s maintainer can call these routes. If using a personal API token, it also needs application:update.

Both accept system_user_ids, a nonempty array of server-account UUIDs. Duplicate IDs are removed.

{
  "system_user_ids": ["7d3984de-49ab-4cc6-bcdf-21fbd35858b8"]
}

Response#

Binding returns 200 with an array of accounts, each containing id, uid, username, server, server_name, login_enabled and is_pinned. A system account, an account bound to a user, or one bound to another application cannot be bound here.

Unbinding returns 200:

{
  "unassigned": 1,
  "system_user_ids": ["7d3984de-49ab-4cc6-bcdf-21fbd35858b8"]
}

Delete an application#

DELETE /api/iam/applications/{id}/

Returns 204 No Content. The application’s service tokens stop authenticating immediately and disappear from the token list. Its roles are removed, provisioning is switched off and its server-account bindings are removed.

curl -X DELETE "https://your-workspace.us1.alpacon.io/api/iam/applications/9d2e4b71-0c3a-4f5e-8b6d-1a2c3e4f5a6b/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""

Error responses#

See Error messages for the coded error format.