Workspace
/
API keys
API keys
One key covers everything a machine needs to do on your behalf. Issue one per service, give it only the scopes it needs, and revoke it on its own when that service goes away.
4 min read
Issuing a key
Keys live under Settings → API keys, alongside the storage access keys. They are different credentials: storage keys sign S3 requests and nothing else, and these authenticate everything that is not S3.
Choose Create API key, name it after the thing that will hold it —
Production server, CI deploy bot — pick an expiry, and tick the scopes it
needs. The secret appears once, on the next screen.
Copy the secret before closing the dialog. It is stored as a hash, so there is no screen anywhere that can show it again — not to you, not to support. A lost key is replaced, not recovered.
A key belongs to the workspace, not to you. Everyone in the workspace sees the list, and an admin can revoke any of them. That is deliberate: the key that most needs killing is usually the one a colleague created before they left.
Scopes
| Scope | What it unlocks |
|---|---|
| Email send | Sending transactional email through Naijamail, from any of the SDKs |
| Databases | Querying and managing your managed databases |
| Deploys | Triggering deploys and reading build logs |
| Platform API | Creating and editing projects, services and variables |
Give a key the narrowest set that lets it do its job. A key that only sends receipts should hold Email send and nothing else — then a leak from that server is an email problem, not an account problem.
Anything outside the three narrow areas requires Platform API. That includes parts of the API added after your key was issued, so a narrow key does not quietly widen as the platform grows.
Using a key
Send it as a bearer token. The API reference covers both surfaces in full — this is the short version:
curl https://api.naijacloud.com/v1/emails \
-H "Authorization: Bearer $NC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"from":"[email protected]","to":["[email protected]"],"subject":"Your receipt","html":"<p>Thanks!</p>"}'The convention is to hold it in NC_API_KEY. Set it as an environment
variable on the service that needs it
rather than committing it, and it will be there on every deploy.
With the email SDKs
The Naijamail SDKs accept a workspace key wherever they accept a Naijamail key, so a key with Email send is all a service needs:
import { Naijamail } from '@naijacloud/email';
// NAIJAMAIL_API_KEY or NC_API_KEY — whichever your service already sets.
const nm = new Naijamail(process.env.NC_API_KEY);To manage sending domains or suppressions through the API as well, the key needs Platform API on top of Email send. Sending is correspondence; changing a verified sending domain is configuration, and a leaked send-only key should not be able to point your domain somewhere else.
Expiry and revocation
Every key gets an expiry, defaulting to 90 days. Never is offered, and it is the wrong default for anything but a credential you have a plan for: a key with no end date outlives the laptop it was made on, the job it was made for, and often the person who made it.
Revoking is immediate and cannot be undone. The next request using that key fails, including sends already queued behind it. The Last used column is there to check before you do — a key that has never been used is safe to remove, and one used three minutes ago is holding something up.
Rotating a key means creating the replacement, deploying it, and then revoking the old one. Revoking first leaves a gap where the service is down.