API Key
An API Key is a secret token that is tied to an application on Unified CDN, allowing your websites or mobile apps to take actions on behalf of you.What API keys can do
- Upload files, get files, rename files, etc
- Do not require your username or password to be stored in your application
- Can be easily revoked if compromised
- Be used securely on a web server
What API keys cannot do
- Access your account directly
- Manage your application/database details on Unified CDN
- Be used securely on the client-side of your application
Making your first request
For this example, we’ll try getting the metadata of a file you’ve uploaded to Unified CDN.1
Uploading a sample file
First, upload a sample file using the dashboard, or use a pre-existing file on your Application. Make sure to copy the file ID first.
2
Obtain an API key
Next, obtain a key from your Unified CDN dashboard. See here for more information. API keys are only shown once, so remember to copy them!
3
Setting up your request
Unified CDN uses the Bearer authentication scheme. This means you need to include your API key in the For this example, we want to get a file’s data, so we’ll use the You should see your file’s metadata printed on your console!
Authorization header of your request, prefixed with “Bearer” like so:/api/files/{id}/get route. Run the following code in your terminal or your application:Terminal
4
Next steps
Now that you know how to authenticate with an API key, you can use it to make requests to any of the other routes in the API.To verify if a route supports API keys, check the Authorizations section of each API route’s page.
Grant code
Grant codes are a more secure way to authenticate with Unified CDN from the client-side of your application. They are tied to and work similarly to API keys, but are short-lived and temporary.What grant codes can do
- A singular action, such as uploading files, getting files, renaming files, etc.
- Do not reveal your API key on the client
- Automatically expire after a short period of time
- Can be set with safeguards to validate client requests (like file types to upload, etc)
What grant codes cannot do
- Take more than 1 action (like uploading a file and then deleting it)
- Be used more than 1 time
- Be used to access your account directly
- Be used to manage your application/database details on Unified CDN
- Generate other grant codes
Grant codes are especially useful when using serverless platforms like Vercel. Vercel has a max payload size (see here) that makes uploading files to Unified CDN through your app’s api routes impossible.By using grant codes, you can first generate a grant code on your server, then pass it to the client components to upload files directly to Unified CDN without needing to go through Vercel.
Making your first request (with grant codes!)
For this example, we will be uploading a single file to Unified CDN from the client-side of your application.1
Obtain an API key
Firstly, Grant codes are tied to and require an API key, inheriting any permissions you set on your key.Obtain a key that can upload files from your Unified CDN dashboard. You should have read the API Key section above to understand how to obtain and use it.
2
Generating a grant code
Next, you need to generate a grant code from your server. Grant codes are generated through the You should see a JSON response with your grant code printed on your console! Make sure to copy the code, you need it later.From the example, we set the guidelines for our grant code in the
/api/grant-codes/generate route, which requires an API key in the Authorization header.For this example, we will generate a grant code that allows uploading 1 file of type image/png. Run the following code on your server:Terminal
data field. Each action has different required and supported parameters. For more configuration options, see here.3
Upload the file
Grant codes uses the Code authentication scheme. This means you need to include your grant code in the Now that you have your grant code, you can use it to upload a file directly to Unified CDN from the client-side of your application.For this example, we will upload a single PNG file using the You should see a JSON response with your uploaded file’s metadata printed on your console!
Authorization header of your request, prefixed with “Code” like so:/api/files/upload route. Run the following code from your client:Terminal
4
Next steps
Check if the file has been uploaded by navigating to the
Files tab on your Application.Now that you know how to authenticate with a grant code, you can use it to make requests to any of the other routes in the API.To verify if a route supports grant codes, check the Authorizations section of each API route’s page.