An API key lets a script, CI job, SDK or MCP client call the HCode API as you. Each key is tied to your account, one organisation and optionally one project, and carries only the permissions you pick.
Before you start
Click API keys in the sidebar, or go to /settings/api-keys. The page and the sidebar link appear only when you signed in to HCode directly. If you came in through a link from the HostAfrica client panel, set a password and sign in with it first; see Password and sign-in. Otherwise key changes are refused with "Sign in directly to manage durable API credentials".
Create a key
- Under Create a key, enter a Name of up to 100 characters, for example "Deployment pipeline".
- Under Access, keep All projects in this organisation or pick one project.
- Set Expires on. It defaults to 90 days from today, and it can be at most a year away. The key stops working at the end of that day.
- Under Permissions, choose Read only or Standard automation, or open Review or customize to tick individual permissions.
- Click Create key.
- Copy the key from Save your key with Copy key, store it somewhere safe, then click I have saved this key.
The secret is shown once and starts with hc_. HCode stores only a hash of it, so a lost key can't be shown again; create a replacement instead.
Organisation keys and project keys
A project key works only on that project. An organisation key works across all projects in the organisation, and you need one to create projects.
Permissions
A key can do something only if it has the permission for it and your current role in the organisation allows it. This is checked on every request, so a key does less if your role is lowered.
| Role | Permissions it can give a key |
|---|---|
| Owner, admin | All of them |
| Member | All except projects:delete, databases:delete and backups:delete |
| Viewer | The read permissions in Read only |
Read only is the default preset. It contains projects:read, configuration:read, deployments:read, operations:read, logs:read, source:read, domains:read, databases:read, database-imports:read, backups:read and credential:read.
Standard automation adds projects:write, configuration:write, deployments:write, runtime:write, operations:write, source:write, domains:write, databases:write and backups:write.
These are only given when you tick them:
| Permission | Allows |
|---|---|
secrets:read |
Reading environment variable values, downloading backup files |
database-query:read |
Running SQL queries |
database-data:read |
Browsing tables, their structure and rows |
database-imports:write |
Uploading and starting database imports |
database-credentials:write |
Creating and revoking database access tokens |
backups:restore |
Restoring a backup |
projects:delete |
Deleting projects |
databases:delete |
Deleting databases |
backups:delete |
Deleting backup schedules |
The API reference shows the permission each endpoint needs.
Warning
A key with projects:write or configuration:write together with deployments:write can deploy code that prints or sends every environment variable and build secret. Treat that combination as if it included secrets:read. Standard automation includes it, so only give it to integrations you would trust with your secrets.
Replace a key
To rotate a key without downtime:
- Click Create replacement next to the key. You get a new secret with the same access and permissions, named after the old key with "(replacement)" added, that expires in 90 days.
- Update your integration to use the new secret.
- Revoke the old key.
Both keys work until you revoke the old one or it expires. Only the person who created a key can replace it.
Revoke a key
Click Revoke next to the key, then Revoke key to confirm. Anything using the key fails on its next request, and a revoked key can't be restored.
Owners and admins see every key in the organisation, marked "Owned by another organisation member" when it isn't theirs, and can revoke any of them. Members and viewers see and revoke only their own.
When someone leaves
When a person is removed from the organisation or leaves it, every API key and every MCP client authorisation they hold for that organisation is revoked at once. Adding them back later doesn't bring the keys back.