← Files Fastly Agent ToolkitARCHIVED FILE
skills/fastly/references/account-management.md
16.8 KB · Oct 10, 2026 · 18:29 UTC
# Fastly Account Management
Base: `https://api.fastly.com` | Auth: `Fastly-Key: $FASTLY_API_TOKEN` | Docs: https://www.fastly.com/documentation/reference/api/account
## Key Concepts
**Token types: personal vs automation.** Personal tokens (created via `POST /tokens`) are tied to the user who creates them and inherit that user's permissions. If the user is deleted or locked, their tokens stop working. Automation tokens (created via `POST /automation-tokens`) are not tied to a user lifecycle -- they survive user account changes and are designed for CI/CD and machine-to-machine use. Automation tokens require a superuser in sudo mode to create.
**IAM model: user groups + service groups + roles.** Access control is built on three primitives. A *user group* contains users (and pending invitations). A *service group* contains services. A *role* defines a set of permissions. You grant access by associating a user group with one or more roles and one or more service groups. Members of the user group then receive the role's permissions on the services in those service groups.
**Superuser vs non-superuser.** Superusers can manage IAM resources, create automation tokens, delete other users, and invite with any role. Non-superusers cannot manage IAM resources, create automation tokens, or delete other users.
**Token scopes are a ceiling, not a floor.** A token's scope limits what it can do, but it can never exceed the permissions of the user (personal tokens) or role (automation tokens) it belongs to.
## Customer / Account
| Action | Method | Endpoint |
| ----------------------- | -------- | ------------------------------- |
| Get current customer | `GET` | `/current_customer` |
| Get a customer | `GET` | `/customer/{customer_id}` |
| Update a customer | `PUT` | `/customer/{customer_id}` |
| Delete a customer | `DELETE` | `/customer/{customer_id}` |
| List users for customer | `GET` | `/customer/{customer_id}/users` |
Update request body is form-encoded. Writable fields include `name`, `billing_contact_id`, `billing_network_type` (`public` or `private`), `billing_ref`, `force_2fa`, `force_sso`, `has_account_panel`, `has_improved_events`, `has_openstack_logging`, `has_pci`, `ip_whitelist`, `owner_id`, `phone_number`, `postal_address`, and contact IDs (`legal_contact_id`, `security_contact_id`, `technical_contact_id`). Read-only response fields: `can_upload_vcl`, `can_reset_passwords`, `can_configure_wordpress`, `has_improved_ssl_config`, `has_pci_passwords`.
## Users & Invitations
### Users
| Action | Method | Endpoint |
| -------------------------- | -------- | ------------------------------------------- |
| Get current user | `GET` | `/current_user` |
| Get a user | `GET` | `/user/{user_id}` |
| Create a user (deprecated) | `POST` | `/user` |
| Update a user | `PUT` | `/user/{user_id}` |
| Delete a user | `DELETE` | `/user/{user_id}` |
| Update password | `POST` | `/current_user/password` |
| Request password reset | `POST` | `/user/{user_login}/password/request_reset` |
User roles: `user`, `billing`, `engineer`, `tls_viewer`, `tls_admin`, `superuser`. Only superusers can modify other users. Non-superusers can only edit their own account. Two-factor attributes (`two_factor_auth_enabled`, `two_factor_setup_required`) are not editable via this endpoint. The `roles` field accepts an array of role IDs for IAM-based role assignment. Deleting a user requires revoking their API tokens first.
### Invitations
Uses JSON:API format (`application/vnd.api+json`).
| Action | Method | Endpoint |
| ----------------- | -------- | ------------------------------ |
| List invitations | `GET` | `/invitations` |
| Create invitation | `POST` | `/invitations` |
| Delete invitation | `DELETE` | `/invitations/{invitation_id}` |
Create payload structure: `data.type` = `"invitation"`, `data.attributes.email`, `data.attributes.roles` (array of role IDs), `data.attributes.limit_services` (boolean), `data.relationships.customer.data` (customer ID/type), and `data.relationships.service_invitations.data` (array of service invitation objects with `permission` and service relationship). Per-service permissions: `full`, `read_only`, `purge_select`, `purge_all`. Superusers can invite with any role. Engineers without per-service limitations can invite new users with the `engineer` or `user` role but cannot modify permissions.
List supports JSON:API pagination: `page[number]`, `page[size]`.
```bash
# Get the current account info
curl -H "Fastly-Key: $FASTLY_API_TOKEN" \
"https://api.fastly.com/current_customer"
# List all users on the account
curl -H "Fastly-Key: $FASTLY_API_TOKEN" \
"https://api.fastly.com/customer/$CUSTOMER_ID/users"
```
## API Tokens (Personal)
Personal tokens are tied to the user who creates them and inherit that user's permission level. Created with username/password authentication (not token auth). Supports 2FA via `Fastly-OTP` header.
| Action | Method | Endpoint |
| -------------------- | -------- | -------------------------------- |
| List my tokens | `GET` | `/tokens` |
| List customer tokens | `GET` | `/customer/{customer_id}/tokens` |
| Create token | `POST` | `/tokens` |
| Get current token | `GET` | `/tokens/self` |
| Get token by ID | `GET` | `/tokens/{token_id}` |
| Revoke current token | `DELETE` | `/tokens/self` |
| Revoke token by ID | `DELETE` | `/tokens/{token_id}` |
| Bulk revoke tokens | `DELETE` | `/tokens` |
Scopes: `global` (default, full access), `purge_select` (purge by URL/surrogate key only), `purge_all` (purge entire service), `global:read` (read-only). Multiple scopes can be combined (space-delimited).
Tokens can be restricted to specific services via `services[]` parameter. Service-limited tokens with `global` or `global:read` scopes can still access non-service endpoints. Limit of 100 active tokens per user (deleted/expired tokens do not count). Optional `expires_at` in ISO 8601 format.
Bulk revoke uses content type `application/vnd.api+json; ext=bulk` with a `data` array of `{id, type: "token"}` objects. Users may only revoke their own tokens; superusers may revoke tokens of others.
Create error codes: `invalid_grant` (bad credentials), `invalid_request` (missing credentials), `invalid_scope` (bad scope), `account_locked`, `2fa.verify` (missing/expired OTP). Format error on `expires_at` returns 422.
```bash
# Get info about the token being used for this request
curl -H "Fastly-Key: $FASTLY_API_TOKEN" \
"https://api.fastly.com/tokens/self"
```
Token creation (`POST /tokens`) returns the `access_token` in the response body.
Ask the user to create and store the token outside the agent session.
Do not execute token-creation commands or request or display their responses in the conversation, even with user confirmation.
## Automation Tokens
Automation tokens are not tied to a specific user account. They are designed for CI/CD pipelines and automated systems. Only superusers can create them (must be in sudo mode). Cannot be created if the account has force SSO or force MFA enabled.
| Action | Method | Endpoint |
| ----------------------- | -------- | ---------------------------------- |
| List automation tokens | `GET` | `/automation-tokens` |
| Create automation token | `POST` | `/automation-tokens` |
| Get automation token | `GET` | `/automation-tokens/{id}` |
| Revoke automation token | `DELETE` | `/automation-tokens/{id}` |
| List token services | `GET` | `/automation-tokens/{id}/services` |
Create request body (JSON): `name` (required), `role` (required -- `billing`, `engineer`, or `user`), `expires_at` (required, null for no expiry), `scope` (default `global`; also `global:read`, `purge_all`, `purge_select`), `services` (optional array of service IDs, empty for all), `tls_access` (boolean). The `access_token` is only returned in the create response -- store it immediately.
Automation tokens do not trigger or apply to Next-Gen WAF features and scopes. All personal token limitations also apply to automation tokens.
Automation token creation (`POST /automation-tokens`) returns the `access_token` only once in the response body.
Ask the user to create and store the token outside the agent session.
Do not execute token-creation commands or request or display their responses in the conversation, even with user confirmation.
## IAM (Identity & Access Management)
IAM uses a three-part model: **user groups** contain users, **service groups** contain services, and **roles** define permissions. Assign roles and service groups to user groups to grant scoped access. Most IAM management endpoints require superuser tokens. Service groups and user groups use `page`/`per_page` pagination.
### Roles
| Action | Method | Endpoint |
| -------------- | ------ | ------------------------- |
| List roles | `GET` | `/iam/v1/roles` |
| Get role by ID | `GET` | `/iam/v1/roles/{role_id}` |
Built-in roles: `superuser`, `engineer`, `billing`, `user`, `tls_admin`, `tls_viewer`. Get role supports `?include=permissions` to return the full permission set. List uses cursor-based pagination (`limit`, `cursor`).
### Permissions
| Action | Method | Endpoint |
| ---------------- | ------ | -------------- |
| List permissions | `GET` | `/permissions` |
Each permission has a `scope` (`service` or `account`), a `resource_name` (e.g., TLS), `resource_description`, and a `name`.
### Service Groups
| Action | Method | Endpoint |
| -------------------------- | -------- | --------------------------------------------- |
| List service groups | `GET` | `/service-groups` |
| Create service group | `POST` | `/service-groups` |
| Get service group | `GET` | `/service-groups/{service_group_id}` |
| Update service group | `PATCH` | `/service-groups/{service_group_id}` |
| Delete service group | `DELETE` | `/service-groups/{service_group_id}` |
| List services in group | `GET` | `/service-groups/{service_group_id}/services` |
| Add services to group | `POST` | `/service-groups/{service_group_id}/services` |
| Remove services from group | `DELETE` | `/service-groups/{service_group_id}/services` |
Add/remove services body: `{"services": [{"id": "..."},{"id": "..."}]}`.
### User Groups
| Action | Method | Endpoint |
| --------------------------------- | -------- | --------------------------------------------- |
| List user groups | `GET` | `/user-groups` |
| Create user group | `POST` | `/user-groups` |
| Get user group | `GET` | `/user-groups/{user_group_id}` |
| Update user group | `PATCH` | `/user-groups/{user_group_id}` |
| Delete user group | `DELETE` | `/user-groups/{user_group_id}` |
| List members | `GET` | `/user-groups/{user_group_id}/members` |
| Add members | `POST` | `/user-groups/{user_group_id}/members` |
| Remove members | `DELETE` | `/user-groups/{user_group_id}/members` |
| List roles in group | `GET` | `/user-groups/{user_group_id}/roles` |
| Add roles to group | `POST` | `/user-groups/{user_group_id}/roles` |
| Remove roles from group | `DELETE` | `/user-groups/{user_group_id}/roles` |
| List service groups in user group | `GET` | `/user-groups/{user_group_id}/service-groups` |
| Add service groups | `POST` | `/user-groups/{user_group_id}/service-groups` |
| Remove service groups | `DELETE` | `/user-groups/{user_group_id}/service-groups` |
Members can be users or invitations. When adding, specify `object: "user"` or `object: "invitation"` in each member entry: `{"members": [{"id": "...", "object": "user"}]}`.
```bash
# List available IAM roles
curl -H "Fastly-Key: $FASTLY_API_TOKEN" \
"https://api.fastly.com/iam/v1/roles"
```
## Billing
### Billing Address
Uses JSON:API format (`application/vnd.api+json`).
| Action | Method | Endpoint |
| ---------------------- | -------- | ----------------------------------------- |
| Get billing address | `GET` | `/customer/{customer_id}/billing_address` |
| Add billing address | `POST` | `/customer/{customer_id}/billing_address` |
| Update billing address | `PATCH` | `/customer/{customer_id}/billing_address` |
| Delete billing address | `DELETE` | `/customer/{customer_id}/billing_address` |
Address attributes: `address_1`, `address_2`, `city`, `state`, `country` (ISO 3166-1 two-letter code), `postal_code`, `locality`. Set `skip_verification: true` to bypass address verification. A 400 response with `candidates` means multiple matching addresses were found and one must be selected.
### Invoices
| Action | Method | Endpoint |
| ------------------------- | ------ | ------------------------------------ |
| List invoices | `GET` | `/billing/v3/invoices` |
| Get invoice by ID | `GET` | `/billing/v3/invoices/{invoice_id}` |
| Get month-to-date invoice | `GET` | `/billing/v3/invoices/month-to-date` |
List supports `billing_start_date`, `billing_end_date` query params (format `YYYY-MM-DD`). Paginated with `limit` (default 100, max 200) and `cursor`. Sorted by billing start date, newest to oldest. Each invoice includes `transaction_line_items` with `product_name`, `product_group`, `product_line`, `region`, `usage_type`, `rate`, and `units`. Month-to-date may return 202 Accepted.
### Usage Metrics
| Action | Method | Endpoint |
| ------------------------------- | ------ | ----------------------------------- |
| Get monthly usage metrics | `GET` | `/billing/v3/usage-metrics` |
| Get service-level usage metrics | `GET` | `/billing/v3/service-usage-metrics` |
Monthly usage requires `start_month` and `end_month` params (format `YYYY-MM`). Maximum period of three months per request. Service-level usage supports optional filters: `product_id` (e.g., `cdn_usage`), `usage_type_name` (e.g., `North America Requests`), `service` (service ID). Paginated with `limit` (default 1000, max 10000) and `cursor`. Only use this API if you do not receive invoices; invoiced customers should use the Invoices API.
## Documentation
URLs below serve Markdown (use the `Accept: text/markdown` header).
| Source | URL |
| --------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Account API reference | `https://www.fastly.com/documentation/reference/api/account` |
| Tokens API reference | `https://www.fastly.com/documentation/reference/api/auth-tokens` |
| Automation tokens reference | `https://www.fastly.com/documentation/reference/api/auth-tokens/automation` |
| IAM roles reference | `https://www.fastly.com/documentation/reference/api/account/roles` |
| User management guide | `https://www.fastly.com/documentation/guides/account-info/user-and-account-management` |
| Invoices API reference | `https://www.fastly.com/documentation/reference/api/account/invoices` |
| Billing, plans, invoices guide | `https://www.fastly.com/documentation/guides/account-info/billing` |
| API token creation and management | `https://www.fastly.com/documentation/guides/account-info/user-and-account-management/using-api-tokens` |
For general Fastly platform guidance, documentation source index, and other specialized skills, see the `fastly` skill.
SHA-256: 5f61367ee03f0a58d1bcb7c8eb38de813354cad07055b8dd40fdf836ad80d78b