Using Basic Authentication to access the Management API

You can use Basic Authentication to access the management API for your Edge for the Cloud account. With Basic Authentication, you pass your credentials (your Apigee account's email address and password) in each request to the management API.

Basic Authentication is the least secure of the supported authentication mechanisms. Your credentials are not encrypted or hashed; they are Base64-encoded only. Instead of Basic Authentication, Apigee recommends that you use OAuth2 or SAML to access the management API.

Basic Authentication format

You can pass your credentials as a Base64-encoded header or as parameters in an HTTP client.

When you pass your credentials in the header, you must Base64-encode them. The following is an example of an encoded HTTP Basic Authentication header:

Authorization: Basic YWhhbWlsdG9uQGFwaWdlZS5jb206bXlwYXNzdzByZAo

With a client such as curl, you pass your credentials with the -u option, as the following example shows:

curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval -u email_address:password

curl encodes your email address and password and adds them to the request's Authorization header for you.

If you omit your password, you will be prompted to enter it.

Note that you must use your Apigee account's email address and not your username in management API calls.

Access the management API

To access the management API with Basic Authentication, you can use a command line utility such as curl or make a request directly in a browser.

Access the management API in a browser

To access the management API in a browser:

  1. Enter the URL of the management API endpoint you want to access; for example:
    https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

    The browser will challenge you with a login prompt:

    Basic Auth Challenge

  2. Enter your Apigee account's email address and password.

    The browser displays the results; for example:

    Basic Auth Results

Access the management API with curl

To use curl to access the management API, you must manually set the Authorization header in a request.

To access the management API with curl:

  1. Base64 encode your email address and password with a tool such as base64; for example:
    echo ahamilton@apigee.com:mypassw0rd | base64

    The base64 tool returns an encoded string:

    YWhhbWlsdG9uQGFwaWdlZS5jb206bXlwYXNzdzByZAo=
  2. Trim any trailing "=" from the end of the encoded string.
  3. Add the encoded string to the Authorization header in your management API request, as the following example shows:
    curl -H "Authorization: Basic YWhhbWlsdG9uQGFwaWdlZS5jb206bXlwYXNzdzByZAo" \
      https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval
    {
      "createdAt" : 1491854501264,
      "createdBy" : "noreply_iops@apigee.com",
      "displayName" : "ahamilton",
      "environments" : [ "prod", "test" ],
      "lastModifiedAt" : 1491854501264,
      "lastModifiedBy" : "noreply_iops@apigee.com",
      "name" : "ahamilton",
      "properties" : {
        "property" : [ {
          "name" : "features.isSmbOrganization",
          "value" : "false"
        }, {
          "name" : "features.isCpsEnabled",
          "value" : "true"
        } ]
      },
      "type" : "trial"
    }

This request gets details about the "ahamilton-eval" organization. For a complete list of management API endpoints, see Apigee Management API Reference.

You must include the Authorization header in every request.

Disable Basic Authentication

You can disable Basic Authentication (as long as OAuth2 or SAML is enabled) by sending a request to Apigee Support.

Scripting guidelines

In some situations, it is not practical to collect the password when the script runs. For example, you may need to run a cron job that fires when no administrators are present. In these situations, you need to make the password available to the script without any human intervention.

Follow these guidelines:

  1. Centralize credentials in a single file that is used as a source for the programs and scripts that you write
  2. Protect the credentials source file to the extent possible using file system security and permissions
  3. Create an automation client with highly restricted permissions on specific resources in your organization.