You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/tutorials/secure-calls-your-api-through-oauth-20-client-credentials). info

> [!WARNING]
> **Important:**When making HTTP requests, never send sensitive data, such as user credentials, in the request URI or in query parameters. You can use any compliant OAuth2 call to make Apigee API calls, but be aware that any sensitive data that appears in a URI or query parameter can be logged or seen by any service where TLS is not in place.

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](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge) 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](https://docs.apigee.com/static/api-platform/images/management-api/oauth-first-request.png) **Figure 1:** OAuth Flow: First request

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

1. You request an access token. You can do this with the [Edge API](https://docs.apigee.com/api-platform/system-administration/management-api-tokens), [acurl](https://docs.apigee.com/api-platform/system-administration/using-acurl), or [`get_token`](https://docs.apigee.com/api-platform/system-administration/using-gettoken). 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

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 Edge OAuth2 service to get tokens, you need to save them for
   later use yourself.
3. 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"
   ```
4. 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](https://docs.apigee.com/static/api-platform/images/management-api/oauth-subsequent-requests.png) **Figure 2:** OAuth Flow: Subsequent requests

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

1. 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.
2. 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](https://docs.apigee.com/static/api-platform/images/management-api/oauth-refresh-token.png) **Figure 3:** OAuth Flow: Refreshing the access token

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

1. You send a request to the Edge API, but your access token has expired.
2. The Edge 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 Edge API with the new access token.
6. 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](https://docs.apigee.com/api-platform/system-administration/using-gettoken): Exchanges your Apigee credentials for access and refresh tokens that you can use to call the Edge API.
- [acurl utility](https://docs.apigee.com/api-platform/system-administration/using-acurl): 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](https://docs.apigee.com/api-platform/system-administration/management-api-tokens): 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](https://docs.apigee.com/api-platform/system-administration/using-acurl).

### 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`](https://docs.apigee.com/api-platform/system-administration/using-gettoken) or the
[Edge OAuth2 service.](https://docs.apigee.com/api-platform/system-administration/management-api-tokens).

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:

- `https://docs.apigee.com/api-platform/system-administration/using-acurl`: No action necessary. `acurl` automatically refreshes the access token when you send a request that contains an outdated one.
- [`get_token`](https://docs.apigee.com/api-platform/system-administration/using-gettoken): Call `get_token` to refresh the access token.
- [Edge OAuth2 service](https://docs.apigee.com/api-platform/system-administration/management-api-tokens#refresh): 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.