/arvancloud-api

name: arvancloud-api
description: Operate ArvanCloud (arvancloud.ir) through its REST APIs, including CDN and DNS records, domains, cache purge, WAF and rate limits, Cloud Server (IaaS v3, v1 and the undocumented v2 backups), Object Storage, Edge Computing, Cloud Container, VOD, Live and Video Ads, plus Let's Encrypt DNS-01 certificates via acme.sh dns_arvan. Use when the user wants to list, create, change or delete anything on ArvanCloud, take an account inventory, find out which account a key belongs to, check quota or usage, or debug an ArvanCloud API error. Also trigger on hosts like napi.arvancloud.ir, ecc.{region}.arvanapis.ir, storage.arvanapis.ir, dejban.arvancloud.ir, an "Apikey" Authorization header, the dns_arvan plugin, or one of the user's ArvanCloud-hosted domains.

ArvanCloud API

Tested reference for driving ArvanCloud's REST APIs from the command line or an agent. Each product has its own base URL and spec, Cloud Server has three API generations, and Object Storage has a second auth scheme. This skill gets those details right so you don't guess.

> Unofficial, community-maintained skill. Not affiliated with or endorsed by ArvanCloud. Hosts, > paths and response shapes were checked against the published OpenAPI specs and read-only live > calls on 2026-09-13. The live specs and API remain the source of truth.

Setup

Keep three things separate: the **secret** (API key) lives in an environment variable, **per-user state** (default region, cert-deploy hooks, notes) lives in a config file outside the skill, and anything the API can tell you (domains, servers, regions) is **fetched live**.

1. Credentials: the plugin's settings or an environment variable, never a file in the skill

Every product except the Object Storage S3 API authenticates with a **machine-user API key**:

Authorization: Apikey <uuid>

**In Claude Code with this plugin installed, use the key from the plugin's settings.** When the user has saved a key there (`/plugin configure arvancloud-api@arvancloud-agent-skill`), it arrives as `$CLAUDE_PLUGIN_OPTION_API_KEY`. If that is set, use it (`CONFIRMED_VAR_NAME=CLAUDE_PLUGIN_OPTION_API_KEY`) and skip the steps below; the bundled scripts pick it up on their own. If it is empty, suggest saving the key in the plugin's settings, since it is then kept in the system credential store, or fall back to an environment variable.

**Everywhere else (Cursor, skills.sh, a manual clone), the key is in an environment variable, and `ARVAN_KEY` is only the default name. Don't assume that's what it's called.** Resolve the real env var every session:

1. If `~/.config/arvan/config.json` exists, read `apiKeyEnv` from it and check that the named var is set (`printenv "$(jq -r .apiKeyEnv ~/.config/arvan/config.json)" >/dev/null`). 2. Otherwise, or if that var is empty, try `$ARVAN_KEY`. 3. If that is also unset, **stop and ask the user** which variable holds the key (or have them export one). A missing key is a question, not a guess. 4. Once confirmed, write the name back so future sessions don't ask:

   tmp=$(mktemp) && jq --arg v "$CONFIRMED_VAR_NAME" '.apiKeyEnv = $v' ~/.config/arvan/config.json > "$tmp" && mv "$tmp" ~/.config/arvan/config.json

The var may hold a bare UUID or a copied `apikey ...` / `Apikey ...` value. The bundled scripts normalize it; for raw curl do the same:

RAW_KEY="${!CONFIRMED_VAR_NAME}"
TOKEN="${RAW_KEY#apikey }"; TOKEN="${TOKEN#Apikey }"
curl -s -H "Authorization: Apikey $TOKEN" "https://napi.arvancloud.ir/cdn/4.0/domains?per_page=100"

**One key sees one account.** Users often hold keys for several accounts. Before any write, run `GET https://dejban.arvancloud.ir/v1/me` and name the account (`data.account.name`) in the confirmation. Treat a `401` as a bad or revoked key and ask the user to check it. A `403` is covered in the errors table below.

**Creating a key:** panel, Settings, IAM, Machine users, Create machine user. The key is shown **once**. Assign IAM access rules per product. Docs: https://docs.arvancloud.ir/fa/developer-tools/api/api-key and https://docs.arvancloud.ir/en/accounts/iam/machine-user. Revoke leaked keys in the same panel page (`panel.arvancloud.ir`; the old `npanel.arvancloud.ir` host redirects there).

2. Per-user state: `~/.config/arvan/config.json`

On first use, create it from the placeholder template:

mkdir -p ~/.config/arvan
[ -f ~/.config/arvan/config.json ] || cp "${CLAUDE_SKILL_DIR}/assets/config.example.json" ~/.config/arvan/config.json

Schema (see `assets/config.example.json`):

• `apiKeyEnv`: name of the env var holding the key (confirmed with the user, see above).
• `acmeTokenEnv`: env var acme.sh's `dns_arvan` reads (default `Arvan_Token`).
• `defaultRegion`: v3 region host to use when unspecified (`ir-central1`, `ir-northwest1`, `eu-west1`).
• `defaultAz`: AZ code for v1/v2 paths and v3 create bodies (e.g. `ir-thr-fr1`).
• `timeoutSeconds`, `maxRetries`, `backoffFactor`: used by `scripts/arvan-api.sh`. It retries only

`429`, and for GET also `5xx` and transient network errors (never DNS or TLS failures).

• `s3AccessKeyEnv`, `s3SecretKeyEnv`, `s3Region`, `s3Endpoint`: Object Storage S3 settings. S3 uses

separate credentials, not the machine-user key.

• `deployHooks`: `domain -> { sshHost, certDirs[], reloadCmd }` for `acme.sh --install-cert`.
• `notes`: `domain -> freeform note` for per-domain quirks.

The **secret never goes in this file**, only the names of env vars. Update the config with the user's OK when you learn a durable fact; don't edit the skill.

3. Everything queryable: fetch live, don't cache

Domains, servers, records, regions and flavors drift. Query them. A stale list is worse than none.

Bundled scripts (bash, curl, jq)

`scripts/arvan-api.sh` is a thin wrapper that resolves and normalizes the key, passes it to curl through a private temp file (never argv or output), retries safely, and prints `HTTP <code>` plus a