Permanent API token explained

Each time you initiate a request to the API, a special access code—an access token—is used. This is needed to ensure that the client has the right to log in to the account and perform certain actions.

JSON Web Token

Access to the Gcore API is provided based on the JSON Web Token (JWT).

It consists of three parts:

1. Header. Contains information about the token type and the digital signature algorithm used.
2. Payload. Data that is transferred with the help of the token: purpose, validity period, date of creation, etc.
3. Signature. Compiled based on the header and payload.

How the JSON Web Token works

1. The client logs in to the system.
2. Gcore API generates a token and sends it to the client.
3. Upon every subsequent request, the client passes on the token.
4. API calculates and verifies the signature.
5. If the signature is valid, API responds to the client.

JSON Web Token limitations

The access token is valid for 1 hour. To issue a new one, Refresh Token is used. With it, users can request a new access token. In this case, the login and password do not need to be re-entered.

The Refresh Token also has a limited lifespan of 24 hours. That means our users need to enter their login and password every 24 hours, which is not too often. This system suits one-time requests perfectly well, but for automated work with our services using API, this creates certain problems.

For example, to set up automatic cache clearing, we need to additionally spell out the authorization logic and send the login and password to the client every time. This is inconvenient and bad for security.

To facilitate regular automated requests to services via API, we issue permanent API tokens.

How a permanent API token works

The main advantage of a permanent API token is that you can set its validity period yourself when you create it. You can even issue it for an unlimited period of time. That makes interaction via API easier: you don’t need to specify and maintain additional logic for a token’s automated issuing process and send a login and password each time.

A permanent API token is a random string. Gcore API stores this string’s hash and owner information.

1. The client sends in a request signed with a permanent token.
2. API verifies the token’s validity, presence of its hash in the database, and the client it corresponds to.
3. If everything is authenticated, API accepts the request.

Which Gcore services can use permanent tokens?

Currently, you can only use your permanent API token in the CDN. It will help you automate any regularly performed processes: for example, cache clearing or requesting statistics.

In the future, we plan to extend the use of these tokens to make working with our other products even more convenient.

How to receive a permanent API token

1. Log in to your account.

2. Go to the API tokens section in your profile and click Create token.

3. Be sure to include the name and role of the token’s creator. Specify the token’s expiration date if needed. Click Create.

4. In a new window, you’ll see the new token. Make sure you save it! We don’t store tokens, so it is not possible to display it a second time.

Use Gcore CDN’s adaptive settings for more convenient and secure content delivery.

Sign up for CDN for free