This guide shows you how to set up an API client for use with many accounts. Ordinarily, an API client can only access the account in which it is created. The process for setting up the specialized API client that lets you make calls across different APIs and accounts is slightly different than the process for creating a regular API client.

Before you start

Using this specialized API client requires the accountSwitchKey query parameter when you make your call. An accountSwitchKey indicates the specific account you want your call to apply to. If you make a call without the accountSwitchKey, the call applies to your API client’s default account.

This API client mimics your Akamai Control Center roles and permissions and lets you manage many accounts programmatically from one API client. To give you this same access, this type of API client uses your Control Center roles and permissions exactly as they appear in Control Center. If you want to change the group and role assignments for the API client, you must change your group and role assignments you have in Luna (or contact an administrator to do it for you). The changes you make to your Luna permissions cascade to the API client automatically and keep it in sync.

Important things to note:

• Credentials on this type of API client expire on the same schedule as your account’s password rotation policy. You cannot edit the expiration date on these credentials, but you can create new credentials for this client.

• The credentials, or tokens, work the same for SAML SSO user as they do for non-SAML SSO users.

• Because this API client uses the same role assignments as the Control Center user the client belongs to, you can follow the same audit trail you normally would and see the API client’s activity just like if it was for the Control Center user.

• You cannot change the owner of these API clients.

• The API client no longer works once the user’s Control Center account is locked or disabled.

To use this type of client with an accountSwitchKey, you’ll need to get specific keys from the Identity Management API. Ensure you’ve provisioned the Identity Management API in your client.

Setup

Before you can make an API call on the Akamai network, you need:

• Access to Akamai Control Center with the correct roles and permissions to create API clients and manage credentials. Contact an Akamai administrator within your company and ask them to create the API credentials for you if you don’t have either of these permissions in your role:

  • IDM: API Clients – User Access
  • IDM: API Clients – Admin Access

• EdgeGrid HTTPie plug-in installed

Create an API client

For this exercise, you’ll create one API client to use across multiple accounts.

1. Launch Identity and Access Management. In Akamai Control Center, click ≡ ⇒ ACCOUNT ADMIN ⇒ Identity & access.

2. From the Users and API Clients tab, click New API client for me to open the Customize API client screen.

3. Click Advanced to create a client for multiple accounts.

4. Select Let this client manage multiple accounts option to let the client make calls to one or more of the accounts you manage.

5. Use presets or change the client’s access level to APIs, permission to groups, and purge methods. For details about roles and permissions and the level of access, see the Identity and Access Management documentation.

6. Click Create API client.

   The client’s name, description, and notification list populate for you in the Details section. You can change this information at any time. The credential and your client token appear in the Credentials section. The credential includes the client token and client secret you need to authenticate Akamai API requests.

7. To check you have access to the Diagnostic Tools API, under Details, click Show additional details, then scroll through the APIs for Diagnostic Tools. If the API isn’t listed, contact your account representative for assistance.

8. Click Download, then add the credential to the .edgerc file.

Add credential to .edgerc file

The credential includes the client token and client secret required to authenticate Akamai API requests. Before you can access the API, you need to configure the file that contains the credentials.

1. Open the file you downloaded in a text editor.

2. Add a line above the credentials as follows: [default].

   

   NOTE: You can add credentials to this file as needed. Separate each set of credentials with a [header] as shown.

3. Save the file in your home directory with the name .edgerc then make API calls with the Diagnostic Tools API.

Make API calls

For this exercise, you’ll use HTTPie to make a simple dig IP address lookup request with the Diagnostic Tools API.

You’ll make the API calls to an account other than the one in which you created your client. Making API calls to another account requires the accountSwitchKey query parameter.

1. Run the List account switch keys operation to retrieve the accountSwitchKey for the account you want to manage.

2. Request the locations of servers in the Akamai network that can run the diagnostic tools.

   $ http --auth-type edgegrid -a default: :/diagnostic-tools/v2/ghost-locations/available?accountSwitchKey=B-4-8IR85
   

   STEP RESULT: You receive a 200 OK response with the location results for the account you passed in the request.

   

3. Execute a dig command to get IP address information for developer.akamai.com in one of the locations. For this example, use Perth, WA, Australia (perth-wa-australia).

   $ http --auth-type edgegrid -a default: ":/diagnostic-tools/v2/ghost-locations/perth-wa-australia/dig-info?hostName=developer.akamai.com&queryType=A&accountSwitchKey=B-4-8IR85"
   

   STEP RESULT: You receive a 200 OK response with the dig results.

   

4. Run the Dig command again, choosing a different location ID from the Ghost location results. For more information, refer to Run dig from a Ghost Location.

Resources

In this exercise, you learned how to create an API client to manage multiple accounts and use that client to make Akamai API calls. Here are some additional resources to expand your knowledge about Akamai APIs.

• View the general Get Started with APIs.

• Download an Open Source API Client that matches your preferred development language.

• Explore the APIs available in the Akamai API Catalog.

• Engage with other developers in the Akamai Developer Community.