Using OAuth2 to access the management API

Apigee Edge lets you make management API calls that are authenticated with OAuth2 tokens.
Support for OAuth2 is enabled by default on Edge for the Cloud accounts. If you are using Edge
for the Private Cloud, you cannot use OAuth2 without
first setting up SAML.

How OAuth2 works (with the Apigee management API)

Calls to the Apigee management API require authentication so that we can be sure that you are who
you say you are. To authenticate you, we require an OAuth2 access token be sent with your request
to access the API.

For example, if you wanted to get details about an organization on Edge, you would send a request to
a URL like the following:

https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

But you can't just send that request without telling us who you are. Otherwise, anyone
could see your org's details.

This is where OAuth2 comes in: to authenticate you, we need you to send us an access token
in that request, too. The access token tells us who you are so we can be sure that you're allowed to
see the details of the organization.

Fortunately, you can get a token by sending your credentials to the Edge OAuth2 service. The
service responds with access and refresh tokens.

OAuth2 flow: The initial request

The following image shows the OAuth2 flow when you access the management API for the first
time:

Figure 1: OAuth Flow: First request

As Figure 1 shows, when you make your initial request to the management API:

The acurl and get_token utilities silently save the access and
refresh tokens to ~/.sso-cli (The refresh token is not written to
stdout.) If you use the management API to get the tokens, you need to save them for
later use yourself.

You send a request to the management API with the access token. acurl attaches
the token automatically; for example:

All of these utilities exchange your Apigee account credentials (email address and
password) for an access token. These tokens are good for 30 minutes.

These utilities also send you a refresh token, which you can use to
exchange for a new access token when your access token expires. A refresh token is good for 24
hours. So, after 24.5 hours, you will need to submit your credentials again for new tokens.

Access the management API with OAuth2

To access the management API, you send a request to an API endpoint and include the access token.
You can do this with any HTTP client, including a command-line utility such as curl,
a browser-based UI such as Postman, or an Apigee utility like acurl.

Accessing the management API with acurl and with curl are described in
the sections that follow.

Use acurl

To access the management API with acurl, your initial request must include your
credentials. The Edge OAuth2 service responds with the access and refresh tokens. acurl
saves the tokens locally.

On subsequent requests, acurl uses the saved tokens in ~/.sso-cli so
that you don't have to include your credentials again until the tokens expire.

The following example shows an initial acurl request that gets details for the
"ahamilton-eval" organization:

In addition to getting details about the organization, this example also shows a second request
that gets a list of policies within the "helloworld" API proxy. The second request uses the
shortening "o" for "organizations" in the URL.

Notice that acurl automatically passes the access token on the second request (you
do not need to pass your user credentials once acurl stores the OAuth2 tokens). It
gets the token from ~/.sso-cli.