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:

OAuth flow: First request
Figure 1: OAuth Flow: First request

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

  1. You request an access token. You can do this with the management API, acurl, or get_token. For example:
    get_token
    Enter username:
    ahamilton@apigee.com
    Enter the password for user 'ahamilton@apigee.com'
    mypassw0rd
    Enter the six-digit code if 'ahamilton@apigee.com' is MFA enabled or press ENTER:
    123456
  2. The Edge OAuth2 service responds with an access token, and prints it to stdout; for example:
    Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
    AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
    NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
    GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
    ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
    RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
    420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
    2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

    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.

  3. You send a request to the management API with the access token. acurl attaches the token automatically; for example:
    acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

    If you use another HTTP client, you be sure to add the access token; for example:

    curl -v https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
      -H "Authorization: Bearer ACCESS_TOKEN"
  4. The management API executes your request and typically returns a response with data.

OAuth2 flow: Subsequent requests

On subsequent requests, you will not need to exchange your credentials for a token. Instead, you can just include the access token you already have, as long as it hasn't expired yet:

OAuth flow: Subsequent requests
Figure 2: OAuth Flow: Subsequent requests

As Figure 2 shows, when you already have an access token:

  1. You send a request to the management API with the access token. acurl attaches the token automatically. If you use other tools, you need to add the token manually.
  2. The management API executes your request and typically returns a response with data.

OAuth2 flow: When your access token expires

When an access token expires (after 30 minutes), you can use the refresh token to get a new access token:

OAuth flow: Getting a new access token
Figure 3: OAuth Flow: Getting a new access token

As Figure 3 shows, when your access token has expired:

  1. You send a request to the management API, but your access token has expired.
  2. The management API rejects your request as unauthorized.
  3. You send a refresh token to the Edge OAuth2 service. If you are using acurl, this is done automatically for you.
  4. The Edge OAuth2 service responds with a new access token.
  5. You send a request to the management API with the new access token.
  6. The management API executes your request and typically returns a response with data.

Get the tokens

To get an access token that you can send to the management API, you can use the following Apigee utilities, in addition to a utility such as curl:

  • get_token utility: Exchanges your Apigee credentials for access and refresh tokens.
  • acurl utility: A curl wrapper that exchanges your Apigee credentials for the tokens, passes the access token in requests, and automatically refreshes the access token when it expires.
  • Token endpoints in the management API: Exchange your Apigee credentials for the access and refresh tokens via a call to the management API.

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:

acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -u ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
mypassw0rd
{
  "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"
}

acurl https://api.enterprise.apigee.com/v1/o/ahamilton-eval/apis/helloworld/revisions/1/policies

[ "SOAP-Message-Validation-1", "Spike-Arrest-1", "XML-to-JSON-1" ]

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.

For more information, see Using acurl to access the management API.

Use curl

You can use curl to access the management API. To do this, you must first get the access and refresh tokens. You can get these using a utility such as get_token or the management API..

After you have successfully saved your access token, you pass it in the Authorization header of your calls to the management API, as the following example shows:

curl -v https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

Token expiration

Tokens have the following durations:

  • Access tokens expire in 1799 seconds (approximately 30 minutes)
  • Refresh tokens expire in 84600 seconds (approximately 24 hours)

Once your access token expires, you can use the refresh token to get a new access token without having to submit your credentials again.

How you refresh your access token depends on which tool you are using:

  • acurl: No action necessary. acurl automatically refreshes the access token when you send a request that contains an outdated one.
  • get_token: Call get_token to refresh the access token.
  • Management API: Send a request that includes:
    • Refresh token
    • grant_type form parameter set to "refresh_token"