Using Basic Authentication to access the Edge API

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

You can use Basic Authentication to access the Edge 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 Edge 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 Edge 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 Edge API calls.

Access the Edge API with curl

You can also manually set the Authorization header request when you use curl to access the Edge API.

Although curl will encode your credentials, as noted above, there may be cases where you do not want to enter your unencoded credentials in your command history.

To manually set the headers and access the Edge API with curl:

1. Base64 encode your email address and password with a tool such as base64. For example:

     read -es PASS
     echo -n ahamilton@apigee.com:$PASS | base64

   The base64 tool returns an encoded string:

   YWhhbWlsdG9uQGFwaWdlZS5jb206bXlwYXNzdzByZAo=

2. Add the encoded string to the Authorization header in your Edge API request, as the following example shows:

       read -es PASS
       BASIC=$(echo -n ahamilton@apigee.com:$PASS | base64
       curl -H "Authorization: Basic $BASIC" \
       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 Edge API endpoints, see Apigee Edge 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 Edge 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.