Authentication
Bytescale supports multiple ways to authenticate your HTTP requests with the Bytescale API and CDN.
Easy Guide:
Set your API key in the apiKey configuration field in the Bytescale SDK or Upload Widget.
Alternatively: use HTTP Bearer or HTTP Basic authentication (if you're not using the Bytescale SDK).
Optional: use JWTs to grant permissions at runtime (e.g. to allow private file downloads).
Done! 🎉
Authentication Methods
The remainder of this page is intended for users who are not using an SDK, or would like to learn more about authentication.
The following table shows the maximum level of access supported by each authentication method; the actual level of access is configurable in the API key permissions and JWT permissions.
This table scrolls horizontally.
| Authentication Method | Where To Use | When To Use | Download (Public Files) | Transform (Public Files) | Download (Private Files) | Transform (Private Files) | Upload File | Copy File | List Folder | Delete File | Delete Folder | Create Folder | Copy Folder | Job Management |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
anywhere | To download public files. | |||||||||||||
backend code | To perform any operation. | |||||||||||||
frontend code | To upload files. | |||||||||||||
frontend code | To download private files, manage files, and upload files. | |||||||||||||
frontend code | To download private files and manage files. | |||||||||||||
frontend code | To download private files. |
1 No Authentication
Bytescale CDN requests (i.e. file download and file transformation requests) don't require authentication by default.
You can change this behavior in the Bytescale Dashboard by making your folder(s) private.
To download a private file, you will need to use one of the authentication methods documented on this page.
All Bytescale API operations (e.g. file uploads, file deletions, etc.) require authentication.
2 API Key Authentication (HTTP Bearer)
The easiest way to authenticate your requests is with HTTP Bearer Authentication, which looks like this:
Authorization: Bearer YOUR_API_KEYWith an SDK:
Set the apiKey configuration field in the Bytescale Upload Widget or Bytescale SDKs.
Without an SDK:
Add an Authorization header to your HTTP request.
Use your API key prefixed with "Bearer " as the header value (see above).
3 API Key Authentication (HTTP Basic)
You can also use HTTP Basic Authentication, which is functionally equivalent to HTTP Bearer Authentication, but follows a different syntax:
Authorization: Basic YXBpa2V5OllPVVJfQVBJX0tFWQ==With an SDK:
Set the apiKey configuration field in the Bytescale Upload Widget or Bytescale SDKs.
Without an SDK:
Configure your HTTP client to use "Basic HTTP Authentication".
Set your username to: apikey (the literal string)
Set your password to: your API key.
Your HTTP client will join the username and password with a : character, base-64 encode the string, and then prepend "Basic " to create the header. We recommend using HTTP Bearer Authentication when manually creating headers, since it's easier to use.
4 API Key + JWT Authentication
You can optionally add a JWT to your API key to grant additional permissions to your users at runtime.
This allows users of your frontend code to gain permissions that exceed that of a public API key.
Authorization: Bearer YOUR_API_KEYAuthorization-Token: eyJhbGciOiJIUzI1NiIsIn.eyJzdWIiOiIxMjM0NTY3ODkwIiwiaWF0Ijo.L8i6g3PfcHlioHCCPURC9pmXT7gdJWith an SDK:
Use the Bytescale JavaScript SDK AuthManager »
The Bytescale JavaScript SDK AuthManager internally uses a combination of JWT Cookies and JWT Bearer Authentication to authenticate client-side requests to the Bytescale API and Bytescale CDN using your API key and JWT.
Without an SDK:
Create a JWT (see: Generating JWTs).
Add your JWT to the Authorization-Token header. (Do not prefix with Bearer.)
Add your public API key to the Authorization header. (Use HTTP Bearer or HTTP Basic authentication.)
Only public API keys can be used with JWTs.
Secret API keys are not intended to be used with JWTs; if you use a secret API key with a JWT, the JWT will be ignored.
5 JWT-Only Authentication (HTTP Bearer)
You can use a JWT without an API key for certain request types (see the Authentication Methods table above):
Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn.eyJzdWIiOiIxMjM0NTY3ODkwIiwiaWF0Ijo.L8i6g3PfcHlioHCCPURC9pmXT7gdJWith an SDK:
Use the Bytescale JavaScript SDK AuthManager »
The Bytescale JavaScript SDK AuthManager internally uses a combination of JWT Cookies and JWT Bearer Authentication to authenticate client-side requests to the Bytescale API and Bytescale CDN using your API key and JWT.
Without an SDK:
Create a JWT (see: Generating JWTs).
Add an Authorization header to your HTTP request.
Use your JWT prefixed with "Bearer " as the header value (see the example above).