Skip to main content
Authentication is required for most routes in the API. There are two main ways to authenticate, using an API Key or using the Grant Code system.

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
For example, you could use an API key on your website’s backend, allowing your website to upload files to Unified CDN through your backend without needing your username or password.
API Keys are considered sensitive information. You should only use them on a server, and never on the client side of your application.If you need to interact with API routes from the client, check Grant Codes for a more secure way.

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 Authorization header of your request, prefixed with “Bearer” like so:
For this example, we want to get a file’s data, so we’ll use the /api/files/{id}/get route. Run the following code in your terminal or your application:
Terminal
You should see your file’s metadata printed on your console!
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
As grant codes are intended to be used directly from the browser, they are more restrictive by nature. Grant codes can only be generated from your server with an API key, and must be set with certain variables to prevent abuse. For example, when uploading files, grant codes must be created with a fixed file number so users don’t upload more or less than the intended amount. Grant codes can also be set with file types when uploading, so users cannot upload files that are not allowed.
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 /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
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 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 Authorization header of your request, prefixed with “Code” like so:
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 /api/files/upload route. Run the following code from your client:
Terminal
You should see a JSON response with your uploaded file’s metadata printed on your console!
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.