Authentication and scopes

Most requests carry an API key. The key’s scopes decide what it may read and change. A few public calls work without a key, such as GET /api/v2/products/vps and POST /api/v2/orders/preview. Their reference page says “Authentication: None”. AI apps that you connect through MCP sign in with your Hostup account instead of a key you create. Connect an AI app shows how.

This page shows how to create and limit a key and how to send it. It ends with what each scope allows.

Create a key

You create keys in the client area under API Management. Only the account owner can do that. Users you have added to the account do not see the page. A key cannot create other keys.

When you create a key you choose:

• Permissions: the scopes. Nothing is ticked from the start. Pick only what the integration needs. Scopes says what each one allows.
• IP Address Restrictions: up to 50 IP addresses or networks, one per line. For example 198.51.100.7, 198.51.100.0/24 or 2001:db8::/32. Leave the field empty to allow every address.
• Expiration date: at most one year ahead. Leave it empty for a key that works until you revoke it.
• DNS restriction: tie the key’s DNS access to certain zones. You can narrow it further to certain records inside a zone.

The key is shown once. Store it in a password manager or a secret store. Keys start with sk_live_.

If a key leaks, roll it in the client area. The old key stops working at once. The new key keeps the same settings.

You can change a key’s scopes, IP addresses and DNS restriction later. The change applies at once. The key itself stays the same. The expiry date cannot be changed. Create a new key for a new date.

Caution

There is no test environment. A key created as a test key starts with sk_test_. It works on your real services all the same. With the right scopes it can order and pay for real. The client area lists it as Live. Rolling it gives a key that starts with sk_live_. Tell your keys apart by their names.

The support guide API keys: create, limit and revoke shows every step in the client area with pictures.

Send the key

Every sample on this site reads the key from $HOSTUP_API_KEY. The Quickstart sets it.

Send the key in the Authorization header as a Bearer token. GET /api/v2/me is a good first call:

GET /api/v2/me

curl "https://cloud.hostup.se/api/v2/me" \
  -H "Authorization: Bearer $HOSTUP_API_KEY"

Response 200

{
  "id": "client_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "authType": "api-key",
  "scopes": ["read:account", "read:vm"],
  "…": "…"
}

scopes lists the scopes on the key. This call needs read:account. A key without it gets 403. The next section shows that response.

When a key is refused

Situation	Response
No key, a mistyped key, a revoked or expired key	401 unauthorized
A request from an IP address the key does not allow	401 unauthorized
The key lacks a scope the endpoint needs	403 forbidden with requiredScopes
The key’s DNS restriction leaves out the zone or record	403 forbidden without requiredScopes
The account is no longer active, for example closed	403 forbidden without requiredScopes
The action is not allowed right now, for example while a VPS is still being set up. The endpoint’s page lists these cases.	403 forbidden without requiredScopes

A key that lacks read:account gets this from GET /api/v2/me:

Response 403

{
  "type": "https://developer.hostup.se/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "code": "forbidden",
  "requiredScopes": ["read:account"],
  "…": "…"
}

requiredScopes lists the scopes the endpoint checks. Add the missing scope to the key: open its menu in API Management and click Edit Permissions. The change applies at once. Then send the request again.

When the list has more than one scope, detail always says the key needs “one of these scopes”. Many endpoints need all of them. The endpoint’s page says which. “The scopes write:vm and rebuild:vm” means all of them. “One of these scopes” means any one.

How scopes cover each other

A scope is written action:resource, for example read:dns or power:vm. Some scopes include others:

• write:all covers every scope on this page.
• read:all covers every scope that starts with read:. It does not cover audit:read or console:services.
• A write: scope covers the read: scope for the same thing. A key with write:dns can also read DNS.
• Some scopes cover more than that. The table below says which.

Give each integration its own key with only the scopes its endpoints need. Each endpoint page in the API reference names them. Then you can revoke one key without stopping the others.

Scopes

One table per area. Each says what a scope lets a key do and which other scopes it covers. Pick the narrowest scope that works.

All resources

Scope	Lets the key	Also covers
read:all	Read everything on the account. Most web hosting reads also need console:services. The audit log needs audit:read.	Every read: scope
write:all	Read, change, order and pay for everything on the account.	Every scope on this page

Account

Scope	Lets the key	Also covers
read:account	Read the account profile.
write:account	Change the account profile and settings.	read:account
audit:read	Read the account’s audit log.

VPS

Scope	Lets the key	Also covers
read:vm	List your VPS. Read their details, status, metrics and settings.
write:vm	Change VPS settings, including backup and snapshot schedules.	read:vm
power:vm	Start, stop and restart a VPS.	read:vm
console:vm	Open the VPS console.	read:vm
backup:vm	Create, restore and delete VPS backups and snapshots.	read:vm
rebuild:vm	Reinstall a VPS from a template. This erases its disk. The call also needs write:vm.	read:vm
write:storage	Add and resize disks, attach ISO images and manage block volumes. Calls that change a VPS’s disks, ISO images or attached volumes also need write:vm.	read:storage
read:network	Read IP addresses and network settings.
write:network	Manage private networks and routed IPv6. Changing a VPS’s IP addresses or reverse DNS also needs write:services.	read:network

Services

These two scopes span VPS and web hosting. They come from before the narrower scopes above. Some endpoints still need them. The endpoint’s page lists them.

Scope	Lets the key	Also covers
read:services	Read all VPS and web hosting accounts. GET /api/v2/cancellations needs it.	read:vm, read:hosting
write:services	Change VPS and web hosting services. It also pays invoices, places orders and manages saved payment methods. POST /api/v2/vps/{id}/network needs it to change a VPS’s IP addresses.	read:services and the VPS, hosting, billing and order write scopes Full list read:services, write:vm, power:vm, console:vm, backup:vm, rebuild:vm, write:storage, write:network, write:firewall, write:hosting, write:billing, write:orders, write:payment_methods and their read: scopes

Web hosting

Scope	Lets the key	Also covers
read:hosting	Read web hosting accounts and what is in them: email accounts, databases, WordPress sites. Most of these calls also need console:services.
write:hosting	Change web hosting resources: email accounts, databases, WordPress, FTP, SSH keys and PHP.	read:hosting
console:services	Reach the hosting control panel and the web hosting calls that go through it. Many web hosting endpoints need it next to read:hosting or write:hosting.

Domains, DNS and CDN

Scope	Lets the key	Also covers
read:domains	Read domains and their settings.
write:domains	Change domain settings, contacts and nameservers. Delete domains.	read:domains, delete:domains
delete:domains	Delete a domain when its lifecycle allows it.	read:domains
transfer:domains	Get EPP codes and handle outgoing transfers. Ordering a transfer to Hostup needs write:orders.	read:domains
read:dns	Read DNS zones and records.
write:dns	Create, change and delete DNS records.	read:dns
write:email	Manage email forwarding.	read:email
read:cdn	Read CDN settings and statistics.
write:cdn	Change CDN settings and purge the cache.	read:cdn

Billing and orders

Scope	Lets the key	Also covers
read:billing	Read invoices, payments and saved payment methods.	read:orders
write:billing	Pay invoices, manage payment methods and place orders.	read:billing, write:orders, write:payment_methods
write:payment_methods	Add, replace and remove saved payment methods.	read:billing
read:orders	Read orders.
write:orders	Place and cancel orders. It cannot manage payment methods.	read:orders

Object storage and support

Scope	Lets the key	Also covers
read:object_storage	Read object storage usage, buckets and access keys.
write:object_storage	Manage buckets and access keys.	read:object_storage
read:support	Read support tickets.
write:support	Open and answer support tickets.	read:support

Scopes you can leave off

The list in the client area also offers scopes for client-area features that are not part of this API. No endpoint in the reference needs them. Leave them off.

The 21 scopes to leave off

read:storage, read:email, read:firewall, write:firewall, read:ip, read:nameservers, read:transfers, read:monitoring, write:monitoring, write:notifications, contacts:read, contacts:write, read:contacts, write:contacts, read:api_keys, write:api_keys, mfa:read, mfa:manage, mfa:verify, read:authentication and bankid:selection.

Next: Errors and retries. What an error looks like and which ones to retry.