Manage many accounts with one API client
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.
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.
Launch Identity and Access Management. In Akamai Control Center, click ≡ ⇒ ACCOUNT ADMIN ⇒ Identity & access.
From the Users and API Clients tab, click New API client for me to open the Customize API client screen.
Click Advanced to create a client for multiple accounts.
Select Let this client manage multiple accounts option to let the client make calls to one or more of the accounts you manage.
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.
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.
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.
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.
Open the file you downloaded in a text editor.
Add a line above the credentials as follows:
NOTE: You can add credentials to this file as needed. Separate each set of credentials with a [header] as shown.
Save the file in your home directory with the name
.edgercthen 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.
Run the List account switch keys operation to retrieve the
accountSwitchKeyfor the account you want to manage.
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.
Execute a dig command to get IP address information for
developer.akamai.comin 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.
Run the Dig command again, choosing a different
location IDfrom the Ghost location results. For more information, refer to Run dig from a Ghost Location.
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.