IAM & API token tools
These tools let an AI agent manage identity and access in an Alpacon workspace: onboarding and offboarding users, organizing them into permission groups, registering machine applications for CI/CD or automation, and issuing API tokens for programmatic access. They back requests like “invite jane@example.com to the workspace,” “add this user to the on-call group as a manager,” or “create an API token scoped to server read access.”
All tools accept workspace (required) and region (optional, defaults to the configured region). These common parameters are omitted from the tables below.
Summary
| Tool | Category | Description | Access |
|---|---|---|---|
list_iam_users | Users | List IAM users in the workspace | Read-only |
get_iam_user | Users | Get details for a specific user | Read-only |
create_iam_user | Users | Create a new user account | Additive |
update_iam_user | Users | Update a user’s profile or active status | Idempotent write |
delete_iam_user | Users | Permanently delete a user | Destructive |
invite_workspace_user | Users | Send an email invitation to join the workspace | Additive |
list_iam_groups | Groups | List IAM groups in the workspace | Read-only |
create_iam_group | Groups | Create a new permission group | Additive |
get_iam_group | Groups | Get details for a specific group | Read-only |
update_iam_group | Groups | Update a group’s display name or description | Idempotent write |
delete_iam_group | Groups | Permanently delete a group | Destructive |
list_iam_memberships | Memberships | List group memberships, optionally filtered by group | Read-only |
add_iam_member | Memberships | Add a user to a group with a role | Additive |
remove_iam_member | Memberships | Remove a user from a group | Destructive |
list_iam_applications | Applications | List machine applications in the workspace | Read-only |
create_iam_application | Applications | Create a new machine application | Additive |
get_iam_application | Applications | Get details for a specific application | Read-only |
update_iam_application | Applications | Update an application’s name or description | Idempotent write |
delete_iam_application | Applications | Permanently delete an application | Destructive |
assign_application_system_users | Applications | Bind system users to an application as service accounts | Idempotent write |
unassign_application_system_users | Applications | Release system users from an application | Idempotent write |
list_api_tokens | API tokens | List API tokens in the workspace | Read-only |
get_api_token | API tokens | Get details for a specific token | Read-only |
create_api_token | API tokens | Create a new API token | Additive |
update_api_token | API tokens | Update a token’s name, status, expiry, or scopes | Idempotent write |
delete_api_token | API tokens | Permanently delete a token | Destructive |
duplicate_api_token | API tokens | Duplicate a token’s configuration into a new token | Additive |
list_api_token_scopes | API tokens | List available permission scopes | Read-only |
list_api_token_presets | API tokens | List available scope presets | Read-only |
Users
Manage IAM user accounts. Group membership is not part of the user record itself—use the Memberships tools to add or remove a user from a group.
list_iam_users
Lists all IAM users in the workspace, returning username, email, active status, and group count (num_groups) for each user.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number for pagination |
page_size | integer | No | Number of users per page |
Example
“List all active users in this workspace”
The agent calls list_iam_users and filters the results client-side by is_active, since the tool itself has no active-status filter.
get_iam_user
Gets detailed information about a specific user by ID: email, first/last name, active status, and group count. Group memberships are not included in this response—use list_iam_memberships to look up which groups a user belongs to.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
user_id | string | Yes | IAM user ID (UUID) |
Example
“Show me the profile for user 550e8400-e29b-41d4-a716-446655440000”
create_iam_user
Creates a new IAM user account. Requires a username and email; the account is active by default. Group assignment happens afterward, via add_iam_member.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
username | string | Yes | Username for the new user |
email | string | Yes | Email address for the new user |
first_name | string | No | First name |
last_name | string | No | Last name |
is_active | boolean | No | Whether the user is active (default: true) |
Example
“Create a user for jane, jane@example.com, and add her to the engineering group”
The agent calls create_iam_user, then add_iam_member with the returned user ID and the engineering group’s ID.
update_iam_user
Updates an existing user’s email, first/last name, or active status. Only the fields you provide are changed (partial update). Group membership changes go through add_iam_member/remove_iam_member, not this tool.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
user_id | string | Yes | IAM user ID to update |
email | string | No | New email address |
first_name | string | No | New first name |
last_name | string | No | New last name |
is_active | boolean | No | New active status |
Example
“Deactivate the user with email old-contractor@example.com”
The agent looks up the user’s ID via list_iam_users, then calls update_iam_user with is_active=false.
delete_iam_user
Permanently deletes a user account. This cannot be undone. If you only want to suspend access, use update_iam_user with is_active=false instead.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
user_id | string | Yes | IAM user ID to delete |
Example
“Delete the user account for the contractor who left last month”
Deletion is permanent. Deactivating the account with update_iam_user preserves the record if you might need it later.
invite_workspace_user
Sends an email invitation to join the workspace. Unlike create_iam_user, the invitee only needs to be identified by email—no existing IAM user record is required. Available on Auth0-enabled (cloud) deployments only.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email address to send the invitation to |
Example
“Invite newhire@example.com to join this workspace”
Groups
Manage IAM permission groups. Groups are named with lowercase letters, digits, hyphens, and underscores only.
list_iam_groups
Lists all IAM groups in the workspace, returning group names, descriptions, and member information.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number for pagination |
page_size | integer | No | Number of groups per page |
Example
“List all IAM groups in this workspace”
create_iam_group
Creates a new permission group. The name must match ^[a-z0-9_-]+$ (lowercase letters, digits, hyphens, and underscores only). Add users to the group afterward with add_iam_member.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Group name (lowercase letters, digits, hyphens, and underscores only) |
display_name | string | No | Human-readable display name |
description | string | No | Description of the group |
Example
“Create a group called on-call with the display name ‘On-call rotation‘“
get_iam_group
Gets detailed information about a specific group by ID: name, display name, description, member count (num_members), and member names.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
group_id | string | Yes | Group ID (UUID) |
Example
“Who’s in the on-call group?”
The agent looks up the group ID via list_iam_groups, then calls get_iam_group to read its member names.
update_iam_group
Updates a group’s display name or description. The group name itself is immutable on the server once created. Only the fields you provide are changed (partial update).
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
group_id | string | Yes | Group ID to update |
display_name | string | No | New display name |
description | string | No | New group description |
Example
“Update the on-call group’s description to mention the new rotation schedule”
delete_iam_group
Permanently deletes a group. This cannot be undone, and members lose any permissions granted only through this group’s membership.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
group_id | string | Yes | Group ID to delete |
Example
“Delete the temp-project group, it’s no longer needed”
Deletion is permanent. Members who relied only on this group for access lose those permissions immediately.
Memberships
Group membership is a separate resource from users and groups—each membership record links a user, a group, and a role.
list_iam_memberships
Lists group memberships in the workspace. Pass group_id to see only the members of a specific group.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
group_id | string | No | Filter results to this group |
page | integer | No | Page number for pagination |
page_size | integer | No | Number of memberships per page |
Example
“Show me everyone in the on-call group and their roles”
add_iam_member
Adds a user to a group by creating a membership record. Requires both the group ID and the user ID.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
group_id | string | Yes | Group ID to add the user to |
user_id | string | Yes | User ID to add to the group |
role | string | No | Role in the group: member, manager, or owner (default: member) |
Example
“Add jane as a manager of the on-call group”
The agent resolves jane’s user ID and the group’s ID, then calls add_iam_member with role="manager".
remove_iam_member
Removes a user from a group by deleting the membership record. Requires the membership ID, not the user or group ID—use list_iam_memberships to find it first.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
membership_id | string | Yes | Membership ID to delete |
Example
“Remove jane from the on-call group”
The agent calls list_iam_memberships filtered by group to find jane’s membership ID, then calls remove_iam_member with that ID.
Applications
IAM applications are machine service accounts for CI/CD pipelines, monitoring integrations, automation, or external integrations. System users (OS-level accounts on servers) can be bound to an application as its service accounts.
list_iam_applications
Lists all IAM applications in the workspace.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number for pagination |
page_size | integer | No | Number of applications per page |
Example
“List all machine applications configured in this workspace”
create_iam_application
Creates a new machine application. Requires a name; service_type must be one of ci_cd, monitoring, automation, or integration (the server defaults to integration when omitted).
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Name of the new application |
description | string | No | Description of the application |
service_type | string | No | ci_cd, monitoring, automation, or integration (server default: integration) |
Example
“Create a CI/CD application called github-actions-deploy”
get_iam_application
Gets detailed information about a specific application by ID.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | Yes | Application ID (UUID) |
Example
“Show me the details for the github-actions-deploy application”
update_iam_application
Updates an application’s name or description. Only the fields you provide are changed (partial update).
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | Yes | Application ID to update |
name | string | No | New application name |
description | string | No | New application description |
Example
“Rename the github-actions-deploy application to gha-prod-deploy”
delete_iam_application
Permanently deletes an application. This cannot be undone.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | Yes | Application ID to delete |
Example
“Delete the old-jenkins-deploy application, we’ve migrated off Jenkins”
Deletion is permanent and cannot be undone.
assign_application_system_users
Binds one or more system users (OS-level accounts on servers) to an application as its service accounts. Requires at least one system user ID.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | Yes | Application ID to assign system users to |
system_user_ids | array | Yes | List of system user IDs (UUIDs) to bind; must contain at least one |
Example
“Bind the deploy system user to the github-actions-deploy application”
unassign_application_system_users
Releases one or more system users from an application. Requires at least one system user ID.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
app_id | string | Yes | Application ID to unassign system users from |
system_user_ids | array | Yes | List of system user IDs (UUIDs) to release; must contain at least one |
Example
“Unbind the deploy system user from the github-actions-deploy application”
API tokens
API tokens grant programmatic access to the Alpacon API. See API tokens for the underlying REST endpoint.
The token-management tools (list_api_tokens, get_api_token, create_api_token, update_api_token, delete_api_token, duplicate_api_token) require a browser sign-in. Called from a local server that uses a static API token, they return 403 Forbidden; connect through the hosted server (browser OAuth) to use them. list_api_token_scopes and list_api_token_presets are not restricted.
list_api_tokens
Lists API tokens in the workspace, with filters for name, enabled status, remote IP, and free-text search.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number for pagination |
page_size | integer | No | Number of items per page |
name | string | No | Filter by exact token name |
enabled | boolean | No | Filter by enabled status |
remote_ip | string | No | Filter by remote IP that last used the token |
search | string | No | Free-text search across name, user agent, and remote IP |
ordering | string | No | Sort field: updated_at or added_at, optionally comma-separated and prefixed with - for descending (server default: -updated_at) |
Example
“List all enabled API tokens in this workspace”
The agent calls list_api_tokens with enabled=true.
get_api_token
Gets detailed information about a specific API token by ID: scopes, expiry, and enabled status.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
token_id | string | Yes | ID of the API token to retrieve |
Example
“Show me the scopes on the CI/CD pipeline token”
The agent finds the token’s ID via list_api_tokens, then calls get_api_token.
create_api_token
Creates a new API token. Scopes can be set explicitly with scopes, resolved from bundled shortcuts with presets (call list_api_token_presets to discover keys), or both—presets are merged with explicit scopes and stored as granular scope strings.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Name of the API token |
scopes | array | No | Permission scopes for the token |
expires_at | string | No | Expiration datetime in ISO 8601 format |
enabled | boolean | No | Whether the token is active (server default: true) |
presets | array | No | Preset scope keys, resolved server-side and merged with scopes |
Example
“Create a read-only monitoring token that expires at the end of the year”
The agent calls create_api_token with scopes set to the read-only monitoring scopes (checked via list_api_token_scopes) and expires_at="2026-12-31T23:59:59Z".
update_api_token
Updates an existing token’s name, enabled status, expiry, or scopes. Only the fields you pass are sent; everything else is left untouched. presets cannot be used here—it’s create-only. expires_at and clear_expires_at are mutually exclusive.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
token_id | string | Yes | ID of the API token to update |
name | string | No | New token name |
enabled | boolean | No | Toggle the token’s enabled state |
expires_at | string | No | New expiration datetime in ISO 8601 format. Mutually exclusive with clear_expires_at |
clear_expires_at | boolean | No | Remove the expiry so the token never expires (default: false). Mutually exclusive with expires_at |
scopes | array | No | Replacement scope list, re-validated against the caller’s permission ceiling |
Example
“Disable the CI/CD pipeline token, we’re rotating it”
The agent calls update_api_token with enabled=false.
delete_api_token
Permanently deletes an API token, revoking it immediately. This cannot be undone.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
token_id | string | Yes | ID of the API token to delete |
Example
“Delete the old staging token, it’s no longer in use”
Deletion is permanent. Consider update_api_token with enabled=false if you might need the token again, or duplicate_api_token to keep a copy before deleting.
duplicate_api_token
Duplicates an existing token’s configuration (scopes, expiry) into a new token. If name is omitted, the server generates one (for example, “Token (copy)”).
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
token_id | string | Yes | ID of the API token to duplicate |
name | string | No | Name for the duplicated token (server auto-generates if omitted) |
Example
“Duplicate the CI/CD pipeline token before I rotate the original”
list_api_token_scopes
Lists the permission scopes available to assign to an API token. Use this before create_api_token to see valid scopes values.
Access: Read-only
Example
“What scopes can I assign to an API token?“
list_api_token_presets
Lists the available scope presets—bundled shortcuts (for example, file_upload) that can be passed to create_api_token via presets instead of listing individual scopes.
Access: Read-only
Example
“What preset scope bundles are available for API tokens?”
Related
- Access control & approvals: manage ACL rules and sudo policies for the users and applications created here
- IAM API: REST endpoints backing the users, groups, and memberships tools
- API tokens API: REST endpoint backing the API token tools