🔐 Authentication

gandi-cli authenticates with Personal Access Tokens (PATs) — not legacy API keys. Gandi has no CLI login: there is no API to mint a token, so you create one once in the dashboard and hand it to the CLI.

Any command run without a token, or with one Gandi rejects, prints step-by-step setup guidance — so you never have to memorise the steps below.

🔑 Create a token

Generate a token at admin.gandi.net → Account → Personal Access Tokens → Create, granting only the permissions you need.

For DNS work, Manage technical configuration (domain:tech) is the only permission strictly required — it covers both DNS records and web redirections. Leave every other product (Email, Web Hosting, Cloud, Certificates…) off unless you use it: a narrower token is a smaller risk if it ever leaks.

⚙️ Configure gandi-cli

The CLI checks the GANDI_API_KEY environment variable first, then the config file — either mechanism works.

Via environment variable

export GANDI_API_KEY="your-token-here"

Via config file

Store the token in ~/.config/gandi/config.toml:

api_key = "your-token-here"

🩹 Troubleshooting

The error you see tells you which case you're in:

• Not authenticated — no token found in the environment or config file. Follow the steps above to create one.
• Token rejected — a token was found but Gandi refused it. Usual causes: it is expired, mistyped / partially pasted, or missing the scope for that command.

✅ Best practices

• ✅ Only grant the permissions each command actually needs.
• ✅ Set an expiry date on the token — Gandi has no API to read or renew it, so rotate it manually when gandi doctor shows the expiry approaching.
• ✅ Use gandi doctor to verify scopes before running commands.