StackRegent API keys for administrators, resellers and customers

How StackRegent API keys decide what a script can do#

StackRegent API keys have no fine-grained scopes. A key acts exactly as the administrator, reseller or customer who made it, with the same rights as that account's login. What a key can reach is therefore decided by:

1. Whose key it is. A customer's key can never see another customer; a reseller's key sees only that reseller's customers, plans and subscriptions; an administrator's key reaches the whole server.
2. The limits on the key itself. Each key can be bound to IP addresses or networks (Allowed from) and can expire after a number of days (Expires).
3. The limits on the account. A restricted administrator's key is held back by Restricted Mode Settings. Reseller and customer keys are held back by their plan: the REST API permission decides whether keys work at all, and each change needs the matching plan permission, such as Databases management or DNS zone management.

There is one set of rules to reason about: if the account cannot do something in the panel, its key cannot do it either. To give a script less than a full account's rights, give it its own account and create the key there, for example a restricted administrator for monitoring, or a customer account that owns only the subscriptions the script manages.

The three kinds of key#

Only the account owner sees the API Keys tab; panel users the owner added to the account do not. Keys cannot be created while an administrator or reseller is working in the account through Log in as customer. A reseller or customer account can hold at most 20 keys.

The REST API permission is checked on every call, not only when the key is made. If a provider removes Ability to use the REST API from a customer's plan, that customer's existing keys stop working at once.

Create an API key#

Step 1: Open the key page#

Administrators open Tools & Settings › Remote API (REST). Resellers and customers click Account and open the API Keys tab. If the tab says your plan does not include the REST API, ask your provider to enable it.

Step 2: Name the key#

Click Create key and enter a Name that says what uses it, for example billing system or nightly backup. The name is required and can be up to 128 characters.

Step 3: Limit where it can be used from#

Under Allowed from, enter the IP addresses or networks of the machines that will use the key, for example 203.0.113.10, 198.51.100.0/24. Separate entries with commas, spaces or semicolons; IPv4 and IPv6 addresses and CIDR networks are accepted, and anything else is refused. Leaving the field empty allows the key from anywhere.

Step 4: Set an expiry#

Under Expires, enter after how many days the key stops working. 0 means it never expires. Give keys for one-off jobs, migrations and contractors a short life.

Step 5: Copy the key#

Click Create. The key, which starts with sr_, is shown once. Copy it into your password manager or the secret store of the system that uses it. The panel keeps only a SHA-256 fingerprint of the key and its first characters, so it cannot show the key again.

The key list shows each key's Name, the start of the Key, the login it Acts as, Allowed from, Last used and Expires.

What each kind of key reaches#

The REST API reference marks every endpoint for each kind of key. In summary:

For reseller and customer keys, every object in the path or body must belong to the account. Asking for another account's subscription, website, database or backup answers 404 as if it did not exist, and endpoints outside the account answer 403 This page is for the server administrator.

What reseller and customer keys can never do#

Reseller and customer keys cannot manage logins: they cannot log in as another account, return from one, change the account password, or list, create or delete API keys. Those calls answer 403 API keys cannot manage logins. and work only in a signed-in panel session.

Plan permissions for changes#

A reseller's or customer's key can read what the account can see, but changes also need the permission in the subscription's plan, exactly as in the panel. Adding a database needs Databases management, editing DNS records needs DNS zone management, adding a mail account needs Mail accounts management, creating a scheduled task needs Scheduled tasks management, and changing hosting settings, virtual directories, SSL or the WAF needs Hosting settings management. Web Deploy publishing settings need Web Deploy publishing even to read. A missing permission answers 403 Your hosting plan does not allow this.

Restricted administrators#

An administrator account can be marked as restricted. A restricted administrator, and every key that administrator creates, can read everything but cannot make changes in the groups switched on under Tools & Settings › Restricted Mode Settings. A blocked change answers 403 Restricted mode does not allow this change. These are the groups and the API paths whose changes each one blocks (GET is never blocked):

This is a property of the administrator account, not of the key. It is also different from license restriction: when the panel's license is not in order, administrator keys can only read and set the license, while reseller and customer keys keep working.

Rotate an API key#

Rotate keys on a schedule and whenever someone who knew a key leaves. A key is shown once and cannot be changed, so rotation means creating a new key, switching the program to it and deleting the old one.

1. Create a new key with the same Allowed from and a fresh expiry.
2. Put the new key into the program and make one test call, such as GET /api/subscriptions?size=1.
3. Check Last used in the key list: the new key shows a time, the old one stops changing.
4. Delete the old key.

Administrators can script these steps with an administrator key, because the key endpoints are part of the API:

# create a key: the answer {"key": "sr_..."} is the only time you see it
curl -s -X POST https://panel.example.com:9443/api/api-keys \
     -H "Authorization: Bearer sr_OLD..." -H "Content-Type: application/json" \
     -d '{"name":"billing system 2026-11","allowed_ips":"203.0.113.10","days":180}'

# list keys: id, name, prefix, admin, allowed_ips, last_used, expires_at
curl -s https://panel.example.com:9443/api/api-keys -H "Authorization: Bearer sr_NEW..."

# delete the old key by its id
curl -s -X DELETE https://panel.example.com:9443/api/api-keys/4 -H "Authorization: Bearer sr_NEW..."

The same in PowerShell:

$base = 'https://panel.example.com:9443/api'
$old  = @{ Authorization = 'Bearer sr_OLD...' }
$body = @{ name = 'billing system 2026-11'; allowed_ips = '203.0.113.10'; days = 180 } | ConvertTo-Json
$new  = (Invoke-RestMethod -Method Post -Uri "$base/api-keys" -Headers $old -Body $body -ContentType 'application/json').key
$hdr  = @{ Authorization = "Bearer $new" }
(Invoke-RestMethod -Uri "$base/api-keys" -Headers $hdr).keys | Format-Table id, name, prefix, admin, last_used, expires_at

Resellers and customers rotate keys in the panel; their keys cannot create or delete keys.

Revoke an API key#

Click the bin icon next to the key and confirm. The key stops working on its next request. Delete a key straight away if it may have leaked, then check the action log for what it did.

Keys also stop working without being deleted when:

• the expiry date passes,
• the administrator who owns the key is no longer active, or the reseller or customer account is suspended or removed,
• a reseller's or customer's plan loses the REST API permission.

Removing an administrator deletes that administrator's keys, and removing a customer or reseller deletes the account's keys.

The temporary key of stackregent api#

On the server, stackregent api calls the API as the main administrator without you creating a key. For each call it makes a key named command line that works only from 127.0.0.1 and ::1, expires after one minute and is deleted when the call ends. See command line.

Good practice#

• Create one key per program, so you can revoke one without breaking the others.
• Always fill in Allowed from with the address of the machine that runs the program.
• Give keys for temporary jobs an expiry.
• Use a reseller or customer key when a script only needs that account; keep administrator keys for server-wide work.
• Keep keys in a secret store, never in a script checked into a repository.