Using OAuth2 to access the Edge API

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

Apigee Edge lets you make Edge 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 or LDAP.

How OAuth2 works (with the Apigee Edge API)

Calls to the Apigee Edge 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 Edge 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 Edge API:

You request an access token. You can do this with the Edge API, acurl, or get_token. For example:

get_token
Enter username:
ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code if 'ahamilton@apigee.com' is MFA enabled or press ENTER:
123456

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 Edge OAuth2 service to get tokens, you need to save them for later use yourself.

You send a request to the Edge 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, make sure to add the access token. For example:
```
curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"
```
The Edge API executes your request and typically returns a response with data.

OAuth2 flow: Subsequent requests

On subsequent requests, you do 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:

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

OAuth2 flow: When your access token expires

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

OAuth flow: Refreshing the access token — **Figure 3:** OAuth Flow: Refreshing the access token

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

You send a request to the Edge API, but your access token has expired.
The Edge API rejects your request as unauthorized.
You send a refresh token to the Edge OAuth2 service. If you are using acurl, this is done automatically for you.
The Edge OAuth2 service responds with a new access token.
You send a request to the Edge API with the new access token.
The Edge 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 Edge 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 that you can use to call the Edge API.
acurl utility: Provides a convenience wrapper around a standard curl command. Constructs HTTP requests to the Edge API, gets access and refresh tokens from get_token, and passes the access token to the Edge API.
Token endpoints in the Edge OAuth2 service: Exchange your Apigee credentials for the access and refresh tokens via a call to the Edge API.

These utilities exchange your Apigee account credentials (email address and password) for tokens with the following durations:

Access tokens expire in 12 hours.
Refresh tokens expire in 30 days.

As a result, once you have successfully made an API call with acurl or get_token, you can continue to use the token pair for 30 days. After expiration, you must re-enter your credentials and get new tokens.

Access the Edge API with OAuth2

To access the Edge 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 Edge API with acurl and with curl are described in the sections that follow.

Use acurl

To access the Edge 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'
[hidden input]
Enter the six-digit code (no spaces) if 'ahamilton@apigee.com' is MFA-enabled or press ENTER:
1a2b3c
{
  "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.

Note 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 subsequent calls.

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

Use curl

You can use curl to access the Edge 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 Edge OAuth2 service..

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

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

The access token is valid for 12 hours after it is issued. After the access token expires, the refresh token can be used for 30 days to issue another access token without requiring credentials. Apigee recommends requesting a new access token only after the referesh token expires, rather than entering credentials and making a new request with every API call.

Token expiration

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.
Edge OAuth2 service: Send a request that includes:
- Refresh token
- grant_type form parameter set to "refresh_token"

OAuth2 for machine users

You can use the acurl and get_token utilities to script automated access to the Edge APIs with OAuth2 authentication for machine users. The following example shows how to use get_token to request an access token and then add the token value to a curl call:

  USER=me@example.com
  PASS=not-that-secret
  TOKEN=$(get_token -u $USER:$PASS -m '')
  curl -H "Authorization: Bearer $TOKEN" 'https://api.enterprise.apigee.com/v1/organizations/...'

Alternatively, you can combine the token request and curl call using the acurl utility. For example:

  USER=me@example.com
  PASS=not-that-secret
  acurl -u $USER:$PASS -m '' 'https://api.enterprise.apigee.com/v1/organizations/...'

In both examples, setting the value of -m to an empty string will prevent a machine user from being prompted for an MFA code.