Authenticating API Requests

There is only one way to authenticate Aspose Cloud REST APIs: JWT Bearer Token.
The JWT token is extracted and validated by our APIs from the Authorization request header.

What is a JSON Web Token (JWT)?

A JSON Web Token is used to send information that can be verified and trusted by means of a digital signature. It comprises a compact and URL-safe JSON object, which is cryptographically signed to verify its authenticity, and which can also be encrypted if the payload contains sensitive information. Because of its compact structure, JWT is usually used in HTTP Authorization headers or URL query parameters.

Structure of a JSON Web Token

A JWT is represented as a sequence of base64url encoded values that are separated by period characters.

header.payload.signature

The header contains the metadata for the token and it minimally contains the type of signature and the encryption algorithm.

Payload (Claims)

In the context of JWT, a claim can be defined as a statement about an entity (typically, the user), as well as additional metadata about the token itself. The claim contains the information we want to transmit, and that the server can use to properly handle JSON Web Token authentication. There are multiple claims we can provide; these include registered claim names, public claim names and private claim names.

Signature

The JWT standard follows the JSON Web Signature (JWS) specification to generate the final signed token. It is generated by combining the encoded JWT Header and the encoded JWT Payload and signing it using a strong encryption algorithm, such as HMAC SHA-256. The signature’s secret key is held by the server so it will be able to verify existing tokens and sign new ones.

How JSON Web Tokens Work

A browser or mobile client makes a request to the authentication server containing user Client Id and Client Secret. The authentication server generates a new JWT access token and returns it to the client. On every request to a restricted resource, the client sends the access token in the Authorization header. The server then validates the token and, if it’s valid, returns the secure resource to the client.

Authorization Flow

The Aspose Cloud REST API supports the OAuth 2.0 protocol and the way to authorize REST API calls is by using client_credentials workflow.

The client_credentials workflow we use is based on a set of keys (client_id and client_secret) which are further used to obtain a token (JWT Token).

Applications

To access the REST API using JWT Token, you need to create an application. To register new applications, login into the Dashboard Developer site using your Aspose Account, and go to the Applicaitons view. Once you create a new application, we will issue a client_id and client_secret that you can use to obtain an JWT Token in order to authenticate your REST API calls. (You can generate new secrets for your Applications, but make sure you update it when issuing new access tokens using those credentials.)

Get Access Token

After you have created a new application you can obtain an access token by sending a POST request to /connect/token endpoint. Still, you must authenticate your access token request using Client Credentials authorization grant type flow:

POST request to: https://api.aspose.cloud/connect/token
  Headers:
    Accept: application/json
    Content-Type: application/x-www-form-urlencoded
    Body:
      grant_type: client_credentials
      client_id: CLIENT_ID
      client_secret: CLIENT_SECRET

The endpoint acts as an authorization server and it verifies your credentials, if they are correct it returns a JSON ticket containing several items, through each, you can find the access_token, expire time of a token etc. The provided access_token is a Bearer Token that you can further use in the Authorization header of your request.

cURL Example

Call REST API

Now that you have the Bearer Token (access_token) generated using the application credentials, you can make API calls and authorize by adding the access token in the ‘Authorization’ header.

  Headers:
    Authorization: Bearer JWT_TOKEN

You authorize with one application, but you can access files from all storages in your account, by specifying storage query parameter (storage, storageName etc.)

cURL Example

Token Lifetime

The time of the tokens is finite. By default, the access_token lifetime is 1 day. Before you create a new access_token, use it and renew it only before it expires. To detect when an access token expires, you must write specific code that will check for any of these:

  • expires_in value in the ticket generated by the /connect/token endpoint.
  • will handle the 401 Unauthorized error responses from the API endpoint and issue a request for a new token.
Request Format