Start here
NetStorage basics
New to the NetStorage HTTP API? This page covers the setup and the rules that trip people up on their first request. It summarises Akamai's documentation, linked in each section.
The four things you need
| Client option | Akamai term | What it is | Where to find it |
|---|---|---|---|
hostname | Connection hostname (HTTP Domain Name) | The API endpoint, always [domain prefix]-nsu.akamaihd.net. The prefix is chosen when the storage group is created. | Control Center → NetStorage → Storage Groups → your group → HTTP Domain Name |
keyName | Upload account name (uploadAccountId) | The account that signs requests. It must not contain commas or spaces. | NetStorage → Upload Accounts |
key | HTTP API key | The shared secret used to sign each request. It is never sent over the wire. | Upload account → Access Methods → NetStorage HTTP CMS API → Copy Key |
cpCode | CP code (upload directory) | A numeric code that is the root directory of your storage group. Every path starts with it. | Storage group details |
Source: Key concepts and terms.
Enable API access
- In Control Center, go to Content delivery → Edge applications → NetStorage and open Upload Accounts.
- Add an upload account or edit an existing one. Its name is your
keyName. - In Access Methods, open the NetStorage HTTP CMS API tab and click Add HTTP API Key. A key is generated for you; Copy Key gives you the
key. - Open Storage Groups, select your group and note the HTTP Domain Name: that is your
hostname.
Wait for propagation. A new or changed upload account can take up to 120 minutes to become active, and Akamai emails you when it is done. Requests before then fail with 403.
Source: Get started.
The endpoint
https://example-nsu.akamaihd.net/123456/static/app.js
^ hostname ^ CP code
^ your path- Use
ssl: truefor https (port 443); otherwise the client uses http (port 80). Your network must allow outgoing traffic on the port you use. - Every path starts with your CP code:
/123456/.... - Paths may be up to 800 characters. NetStorage uses ISO-8859-1 by default, so characters in the range 32–255 work out of the box; the client encodes paths to match.
Sources: Format an API call, Technical limits.
How each request is signed
The client does this for you, but knowing it helps when you debug a 403. Each request carries three headers:
| Header | Contains |
|---|---|
X-Akamai-ACS-Action | The operation as a query string, starting with version=1, e.g. version=1&action=upload. One action per request. |
X-Akamai-ACS-Auth-Data | 5, 0.0.0.0, 0.0.0.0, [unix time], [unique id], [keyName]. Version 5 means HMAC-SHA256, the cipher Akamai recommends. |
X-Akamai-ACS-Auth-Sign | Base64 HMAC-SHA256, using your key, of the Auth-Data value, the request path, a newline, x-akamai-acs-action: plus the action value, and a final newline. |
Keep your clock in sync. The time in the signature must be within one minute of Akamai's time, or the request fails with 403. Run NTP on servers and CI runners.
See it for yourself in the playground, which shows the exact string that gets signed. Source: Signature header authentication.
Limits worth knowing
| Limit | Value |
|---|---|
| Write operations (upload, delete, rename, mkdir, rmdir…) | About 50 per second per storage group, averaged over 10 seconds |
| Read operations (download, stat…) | About 1,000 per second per storage group |
dir and list | Each counts as 10 reads |
| Largest object | 150 GB; split files over 100 GB into parts |
| Path length | 800 characters, including directories |
| Concurrent connections | Up to 90 per upload account |
Akamai calls these recommended maximums rather than guarantees: rate limiting can start earlier, and three-replica storage groups allow fewer writes. Exceeding them returns 429; back off and retry. Very large directories can time out when listed, so page through them with max_entries. Source: Technical limits.
Replication and reading back
NetStorage keeps copies of your content in more than one place. The HTTP API does not chase requests to other replicas, so right after an upload, a stat or download can briefly see an older version or nothing at all. Akamai recommends serving content to users through a delivery product with NetStorage as the origin, and not downloading files larger than 1 GB through this API. This client also holds a download in memory before writing it, so plan memory for large files. Source: Technical limits.
Common errors
| Status | Usually means | What to check |
|---|---|---|
403 | Authentication or authorization failed, or the action is not allowed with that HTTP method. | Clock within one minute; the right hostname, keyName and key; the upload account has finished propagating. The response body often says more. |
404 | The path does not exist. | The CP code and path; replication delay right after an upload. |
412 | A precondition failed. | The content changed since you last read it. |
429 | Too many requests. | Slow down and retry with backoff; see the limits above. |
500 | An error on Akamai's side. | Retry later; contact Akamai support with the response details if it persists. |
Remember that the client resolves promise methods for HTTP errors; use the callback form to read res.statusCode. Source: Errors.