Authentication

Some of this API's operations are publicly accessible and don't require authentication. However, all operations that affect your account require either a personal access token or OAuth authentication, when using third-party applications.

Personal access tokens

The easiest way to access the API is with a personal access token (PAT) generated from ​Akamai​'s Cloud Manager portal. This token should only allow the level of access needed by the application.

To create one:

1. Log in to Cloud Manager and go to the API Tokens page of the My Profile section. See View Personal Access Tokens.

2. Click Create a Personal Access Token. The Add Personal Access Token panel launches.

3. Set these options:

   • Label. Enter a name for the token that makes it easy to identify and understand its intended use.

   • Expiry. Select an expiration timeline. You can't change this after you create the token.

   • Access. Set the level of access for each API product or service ("category"). Select Read/Write to allow full access to that category. You can't change this after you create the token.

4. Click Create Token. A dialog box opens and displays your new personal access token.

📘

The token is only revealed now

Save this in a safe place, such as a password manager. After closing this prompt, you can't view the token string again.

PAT authentication

📘

The scopes listed in the OAuth model apply to this security model, too.

Revoke a personal access token

If you want to decommission a token or think it may have been compromised, you can revoke it. Once revoked, any application using the token will no longer be authorized to access your account through the Linode API.

1. Log in to ​Akamai​'s Cloud Manager.

2. Click your username at the top of the screen and select API Tokens under the My Profile section.

3. Find the token you wish to revoke and click Revoke.

📘

You may need to click ... to access this option from the drop-down.

4. In the pop-up that appears, click Revoke to confirm.

OAuth

If you're designing an application that can authenticate with an arbitrary Linode user, use the OAuth 2.0 workflows we offer here.

👍

If you only need to access the Linode API for personal use, create a personal access token.

Before you begin

To implement OAuth in your application, first you need to create an OAuth client. You can do this with the Linode API. Consider these points when creating this client:

• The response from the Create an OAuth client operation gives you a client_id and the client secret. Store these values for use in the future.

• Clients can be public or private, and are private by default. You can choose to make the client public during creation.

  • The private client. Use this with applications that can securely store the client secret. For example, an application running on a secured server that only the developer has access to would use a private OAuth client. This is also called a confidential client in some OAuth documentation.

  • The public client. Use this in applications that can't guarantee security of the client secret. For example, this could be a native app running on a user's computer that can't keep the client secret safe, as a user could potentially inspect the source of the application. So, native apps or apps that run in a user's browser should use a public OAuth client.

• The redirect_uri is displayed as the Callback URL in Cloud Manager.

For a detailed example of an OAuth 2.0 implementation, see How to Create an OAuth App with the Linode Python API Library.

OAuth authentication

The OAuth authentication workflow is a series of exchanges between your third-party app and ​Akamai​ cloud computing services. The user is authenticated before an application can start making API calls on the user's behalf.

📘

The OAuth 2.0 Authorization Framework (RFC 6749)

Our OAuth authorization follows the methodology explained in RFC 6749, with these considerations:

• Looking at the diagram in section 1.2 of RFC 6749, login.linode.com serves as the Resource Owner and the Authorization Server. We refer to this as the login server throughout this section. The Resource Server is api.linode.com, which we refer to as the API server here.

• The OAuth spec refers to the private and public workflows we call out here as the authorization code flow and implicit flow, respectively.

The private workflow

1. The user visits the application's website and is directed to login with ​Akamai​ cloud computing services.

2. Your application then redirects the user to our login server with the client application's client_id and requested OAuth scope, which needs to appear in the URL of the login page. See the "OAuth scopes" listing in OAuth reference for details.

3. The user logs into the login server with their username and password.

4. The login server redirects the user to the specified redirect URL with a temporary authorization code (exchange code) in the URL.

5. The application issues a POST request to the login server with the exchange code, client_id, and the client application's client_secret:

   • Make an HTTP POST request as application/x-www-form-urlencoded or as multipart/form-data to:

     https://login.linode.com/oauth/token
     

   • Include the following parameters in the POST body:

     PARAMETER	DESCRIPTION
     client_id	Your app's client ID.
     client_secret	Your app's client secret.
     code	The exchange code you just received from the redirect.

6. The login server responds to the client application with new OAuth tokens. The access_token is set to expire in two hours. Store these values from the response:

   • "access_token": "abc123def456hij789klm"
   • "refresh_token": "012nop345qrs678tuv901"

7. Make authenticated HTTP requests to the API for the next two hours by including the access_token in this header with each request:

   Authorization: Bearer abc123def456hij789klm
   

8. After the access_token has expired, the application issues a POST request to the login server to request a new one using the the refresh_token:

   • Make an HTTP POST request as application/x-www-form-urlencoded or as multipart/form-data to:

     https://login.linode.com/oauth/token
     

   • Include the following parameters in the POST body:

     PARAMETER	DESCRIPTION
     grant_type	Set this to the refresh_token when refreshing access.
     client_id	Your app's client ID.
     client_secret	Your app's client secret.
     refresh_token	The refresh_token received from the previous response.

A response body is returned with a new access_token with a two-hour TTL, as well as a new refresh_token that can be used to repeat the process.

The public workflow

1. The user visits the application's website and is directed to login with ​Akamai​ cloud computing services.

2. Your application then redirects the user to our login server with the client application's client_id and requested OAuth scope, which needs to appear in the URL of the login page. See the "scopes" listing in OAuth reference for details.

3. The user logs into the login server with their username and password.

4. The login server redirects the user back to your application with an OAuth access_token embedded in the redirect URL's hash. This is temporary and expires in two hours. No refresh_token is issued. So, once the access_token expires, you need to issue a new one. To do this, the user needs to log in again.

OAuth reference

• Authorization URL. https://login.linode.com/oauth/authorize
• Token URL. https://login.linode.com/oauth/token
• OAuth scopes. A scope specifies the level of access the client is requesting. It refers to the information or functionality that the application can access, and whether read-only or write access is allowed. These are the scopes supported with the Linode API: