Manage many accounts with one API client

This guide shows you how to set up a single API client for use with many Akamai Control Center accounts. Ordinarily, an API client uses a single account, the one you used to log in to Control Center and then create the API client. To set up this specialized API client, you need to follow a few more steps.

Before you start

You need to do a few things:

  • Determine the API you want to use and get the related Akamai product added to your contract. Each Akamai API typically corresponds with a specific Akamai product. Before you can use that API, work with your Akamai account rep to get the product added to your contract.

  • Get the API service’s name.

  • Determine the level of access you’ll need to work with the API. This can be READ-WRITE, READ-ONLY, or ADMIN.

    Tip: You can find all of this info in the Get started section of each Akamai API doc. See all Akamai APIs.

  • Get access to the Identity Management API. You’ll use it to get specific keys used to switch between accounts when making calls to your chosen API. Talk to your local Akamai administrator or your Akamai account rep to ensure you have access to this API.

Pick your API client tool

Decide which tool you’ll use to make requests:

  • HTTPie. Use this command-line tool to issue individual calls from a prompt.
  • Postman. Go with this if you want the assistance of a graphical user interface to issue calls to the API.

We’ll talk more about these tools and how they fit into this process later.

Authentication with EdgeGrid

You need to properly authenticate your API requests, whether they’re made directly to an API endpoint or through a request tool that wraps API requests. Akamai uses a proprietary authentication system called EdgeGrid, for APIs deployed through Control Center.

Consider these points before you set up authentication for an API client for use with many Control Center accounts:

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

  • The credentials, or tokens, work the same for a 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 were for the Control Center user.

  • You can’t change the owner of these API clients.

  • The API client will no longer work if the user’s Control Center account is locked or disabled.

Set up permissions

You use Control Center to set up this authentication and you need the correct roles and permissions on your account. Talk to the Akamai administrator in your organization, or contact your Akamai account rep to get both of these Identity and Access Management permissions set in your role:

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

Set up authentication for the API client

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

  1. Launch Identity and Access Management. In Control Center, you can navigate there by selecting ☰ → ACCOUNT ADMIN → Identity & access.

  2. From the Users and API Clients tab, click Create API client, then select Myself under Select API client type.

    Note: If you don’t have access to the Identity and Access Management tool, you don’t see the Create API client option, or you don’t see the Myself option, contact your local admin or your Akamai account rep for assistance.

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

  4. Enable the Let this client manage multiple accounts option. This lets the client make calls to one or more of the accounts you manage.

  5. Use presets or change the APIs this client can access, its Groups permissions, and Purge selections. 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. Click Show additional details. Make sure you have access to both the Identity Management: API and the target API you want to use. Enter each API’s service name in the Filter field to verify that it’s included and that you have the proper level of access. If either are missing, or the wrong level of access is set, contact your local administrator or Akamai account rep.

  8. Click Hide additional details to return to the Details and Credentials information.

  9. Keep the API client for you page open. You’ll need the information displayed here throughout the process.

Apply the authentication in HTTPie

To use its CLI to issue API calls, apply the credential for HTTPie via python.

Python version

Make sure you have at least version 3.6 installed. You can download the latest version from python.org.

Use pip to install

To simplify the install process, we use pip. It works on Linux, macOS, and Windows, and always provides the latest version of HTTPie. Since we’re using Python v3.6 or greater, pip is already installed. Use this command to verify:

  • Linux/macOS

    $ python -m pip --version
pip X.Y.Z from .../site-packages/pip (python X.Y)

  • Windows

    C:\> py -m pip --version
pip X.Y.Z from ...\site-packages\pip (python X.Y)

Install HTTPie

Once you’ve verified that pip is installed, run this command to install HTTPie and upgrade it to the most recent version:

  • Linux/macOS

    $ python -m pip install --upgrade httpie

  • Windows

    C:\> py -m pip install --upgrade httpie

Install httpie-edgegrid

You also need the httpie-edgegrid plugin for use in authentication. It’s already available via pip, so you can quickly install it.

  1. From a terminal window or command prompt, navigate to a directory where you want to install the plugin. It doesn’t have to be installed in the same destination as HTTPie.

  2. Run this command to install:

    pip install httpie-edgegrid

  3. You can verify installation and check the version by running this command:

    pip show httpie-edgegrid

Set up your .edgerc file

The httpie-edgegrid plugin relies on a credentials file that Control Center creates when you set up authentication for an API client.

  1. Return to the API client for you page in Control Center. It’s in the Identity and Access Management tool.

  2. Click Download in the Credentials section.

  3. Open the downloaded file with a text editor and add the value [default] as a header above all text. Your finished file should look like this:

  4. Save the file in your home directory using .edgerc as the filename. Here are some examples of the default home directory location for various operating systems:

    • Linux and macOS. /Users/{login}/.edgerc
    • Windows. C:\Users\{username}\.edgerc

You’re ready to go! See Make API calls with HTTPie for call-formatting specifics and usage examples.

Apply the authentication in Postman

Postman has Akamai EdgeGrid authentication built in. You can easily add your credential to authenticate and start using Akamai’s APIs.

Download and install the Postman app

Postman offers apps for Linux, macOS, and Windows. You can get the app from Postman’s website. See Postman’s learning center article for installation details on each operating system.

Apply your credential authentication values

You need authentication values from the credential you created when you set up authentication for an API client. You apply these values in Postman for access.

  1. Launch Postman.

  2. Select Collections from the toolbar and make sure New Collection is selected.

  3. Click the pencil icon to the right of New Collection to set a new name. We’re using Get started with Akamai APIs. You can use whatever you like.

  4. Click Authorization.

  5. From the Type menu, select Akamai EdgeGrid.

  6. Return to the API client for you page in Control Center. It’s in the Identity and Access Management tool.

  7. In the Credentials section, copy the client_secret value.

  8. Return to Postman and paste it in the Client Secret field.

  9. Repeat steps 5–7 for both the access_token and client_token values.

    Tip: Don’t close the API client for you page in Control Center. You use it to set up variables in the next process.

  10. Click Save.

Set up variables

You can use Postman’s Variables feature to assign a reusable value to a variable and call on it whenever you need it. This can help protect sensitive data like your authorization values, or you can use one to quickly call a fixed value in an API request. Here we cover some optional but recommended variables you can create.

First, let’s store the base URL used for all Akamai APIs as a variable. This way, you can quickly call on it when making a request, rather than typing it manually each time.

  1. Return to the API client for you page in Control Center. It’s in the Identity and Access Management tool.

  2. In the Credentials section, copy the Host value.

  3. Back in Postman, make sure your Collection is active and click the Variables tab.

  4. In a new row, click Add a new variable and type base_url as its name.

  5. Click its INITIAL VALUE column cell, type https://, and Paste. The CURRENT VALUE column defaults to this same value. Leave it as is.

  6. Click Save.

More on how to use this variable later. Next, let’s hide your Access Token, Client Token, and Client Secret values using variables.

  1. With your Collection selected, click the Authorization tab.

  2. Copy the value you set as your Access Token.

  3. Select the Variables tab. Click Add a new variable in the table. Type access_token as the name.

  4. Click in the INITIAL Value column and Paste.

  5. Select the Authorization tab and repeat steps 2–4 for the Client Token and Client Secret values, naming the variables client_token and client_secret, respectively.

  6. Return to the Authorization tab and delete all content in the Access Token field.

  7. Type {{access in the Authorization field and select the access_token variable from the drop-down.

  8. Repeat step 7, typing {{client to find these variables for both the Client Token and Client Secret.

  9. Click Save.

Your token and secret values are now protected from direct view.

You’re ready to go! See Make API calls with Postman for call-formatting specifics and some usage examples.

Make API calls with HTTPie

HTTPie follows a generic path to authenticate and make a request to an Akamai API:

$ http --auth-type=edgegrid -a default: :{akamai_api-endpoint}

You probably recognize some values here, but some may be unfamiliar:

  • auth-type=edgegrid. This tells the request to use edgegrid for authentication.

  • -a default. This tells the request to reference the [default] section of your .edgerc file for credentials.

  • {akamai-api-endpoint}. This endpoint corresponds to the specific API operation you want to call. You can find a list and explanation of available endpoints in the relevant API’s documentation.

HTTPie sample usage

Here we’re using HTTPie to make a simple dig IP address lookup request using the Diagnostic Tools API:

  1. To start, you need to query the Identity Management API to get your accountSwitchKeys. You’ll append one of these values as a query string in a request to the Diagnostic Tools API, to use that specific account. List your account switch keys.

$ http --auth-type=edgegrid -a default: :/identity-management/v2/api-clients/self/account-switch-keys

  1. Store the accountSwitchKey value from the response, based on the applicable accountName.

    [
    {
        "accountName": "Rae Inc.",
        "accountSwitchKey": "1-EFGH"
    },
    {
        "accountName": "Doe_Indirect Customer",
        "accountSwitchKey": "1-ABCD:Z-XYZ"
    },
    {
        "accountName": "Doe_Direct Customer",
        "accountSwitchKey": "1-ABCD:Z-PQR"
    }
]

  2. Request the locations of servers in the Akamai network that can run the diagnostic tools, and append the applicable accountSwitchKey as a query string.

    $ http --auth-type=edgegrid -a default: :/diagnostic-tools/v2/ghost-locations/available?accountSwitchKey=1-EFGH

    The 200 OK response shows the location results:

    HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 6524
Content-Type: application/json;charset.UTF-8
Date: Mon, 25 Jun 2018 18:39:57 GMT
Server: Apache-Coyote/1.1
X-Trace-Id: c0545b3136fb13bb6

{
    "locations": [
        {
            "id": "oakbrook-il-unitedstates",
            "value": "Oakbrook, IL, United States"
        },
        {
            "id": "vienna-austria",
            "value": "Vienna, Austria"
        },
        {
            "id": "saintpetersburg-russianfederation",
            "value": "Saintpetersburg, Russian Federation"
        },
        {
            "id": "goteborg-sweden",
            "value": "Goteburg, Sweden"
        },
        {
            "id": "perth-wa-australia",
            "value": "Perth, WA, Australia"
        }
    ]
}

  3. Request IP address information for Perth, WA, Australia, using the specific locationId from the previous call, perth-wa-australia, and append the applicable accountSwitchKey as a query string.

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

    The 200 OK response shows location-specific results:

    HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 3073
Content-Type: application/json;charset.UTF-8
Date: Mon, 25 Jun 2018 18:49:48 GMT
Server: Apache-coyote/1.1
X-RateLimit-Limit: 10
X-Ratelimit-Remaining: 9
X-Trace-Id: 68585b31394a1a20b

{
    "digInfo":
        "answerSection": [
            {
                "domain": "developer.akamai.com.",
                "preferenceValue": null,
                "recordClass": "IN",
                "recordType": "CNAME",
                "ttl": 300,
                "value": "san-developer.akamai.com.edgekey.net."
            },
            {
                "domain": "san-developer.akamai.com.edgekey.net.",
                "preferenceValue": null,
                "recordClass": "IN",
                "recordType": "CNAME",
                "ttl": 300,
                "value": "e24856.dscx.akanmiedgeonet."
            }
        ]
    }
}

Make API calls with Postman

Use Postman to make requests to an Akamai API straight from its interface. It offers several extra features that make it a little easier to manage complex calls too.

Postman sample usage

Here we’re using Postman to query the Diagnostic Tools API. We’re looking to view all of the IP addresses assigned to a specific Global Traffic Management (GTM) property.

Note: This example assumes you’ve set up variables in Postman.

  1. Launch Postman.

  2. Select Collections → {collection-name} and click New Request.

  3. Ensure the method is set to GET and type {{base in the Enter request URL field.

  4. Select the base_url variable from the drop-down menu. This inserts the base URL variable.

  5. Query the Identity Management API to get your accountSwitchKeys. You’ll append one of these values as a query string in a request to the Diagnostic Tools API, to use that specific account. Add the List your account switch keys endpoint. The full value should look like this:

{{base_url}}/identity-management/v2/api-clients/self/account-switch-keys

  1. Click Send. Note the accountSwitchKey value from the response, based on the applicable accountName.

    [
    {
        "accountName": "Rae Inc.",
        "accountSwitchKey": "1-EFGH"
    },
    {
        "accountName": "Doe_Indirect Customer",
        "accountSwitchKey": "1-ABCD:Z-XYZ"
    },
    {
        "accountName": "Doe_Direct Customer",
        "accountSwitchKey": "1-ABCD:Z-PQR"
    }
]

  2. Add the list GTM properties endpoint to show all GTM properties. Append the applicable accountSwitchKey as a query string. The full value should look like this:

    {{base_url}}/diagnostic-tools/v2/gtm/gtm-properties?accountSwitchKey=1-EFGH

  3. Click Send. The interface shows a response similar to this:

    {
    "gtmProperties": [
        {
            "property": "origin",
            "domain": "akadns.net",
            "hostName": "origin.akadns.net"
        },
        {
            "property": "origin-r3h",
            "domain": "akadns.net",
            "hostName": "origin-r3h.akadns.net"
        }
    ]
}

  4. Find the applicable hostName for your GTM property and store its property and domain values.

  5. Replace the endpoint path with the list IP addresses for a GTM property operation. Keep the {{base_url}} variable value in this field.

  6. Replace the {property} and {domain} variable values with the ones you stored and append the applicable accountSwitchKey as a query string.

    {
    "gtmPropertyIps": {
        "property": "origin",
        "domain": "akadns.net",
        "testIps": [
            "1.23.45.678",
            "191.011.121.314",
            "15.16.171.81",
            "192.02.122.23",
            "24.25.262.72"
        ],
        "targetIps": [
            "182.93.03.132",
            "133.34.35.363",
            "273.83.94.04"
        ]
    }
}

Now you can review all of the test and target IP addresses that have been assigned to your selected GTM property.

Tip: Click Save at the top right to reuse this operation in Postman. You won’t have to run the original operation to get the property and domain values again.

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.

Akamai.com Contact us Legal & privacy Portal terms of use
Copyright © 2021 Akamai Technologies, Inc. All rights reserved