Basic authentication is one way to authenticate when making calls to the Edge management API.
For example, you can make the following `curl` request to the Edge management API to access
information about your organization:

```
curl -u USER_NAME:PASSWORD https://MS_IP_DNS:8080/v1/organizations/ORG_NAME
```

In this example, you use the `curl` `-u` option to pass Basic authentication
credentials. Alternatively, you can pass an OAuth2 token in the `Bearer` header to make
Edge management API calls, as the following example shows:

```
curl -H "Authorization: Bearer ACCESS_TOKEN" https://MS_IP_DNS:8080/v1/organizations/ORG_NAME
```

After you enable an external IDP for authentication, you can optionally disable Basic
authentication. If you disable Basic
authentication, all scripts (such as Maven, shell, and `apigeetool`) that
rely on Edge management API calls supporting Basic authentication no longer work. You must update
any API calls and scripts that use Basic authentication to pass OAuth2 access tokens in the
`Bearer` header.

## Get and refresh tokens with get_token

The [`get_token`](https://docs.apigee.com/api-platform/system-administration/using-gettoken) utility exchanges your Basic authentication credentials (and in some cases a
passcode) for an OAuth2 access and refresh token. The `get_token` utility accepts your
credentials and returns a valid access token. If a token can be refreshed, the utility refreshes
and returns it. If the refresh token expires, it will prompt for user credentials.

The `get_token` utility stores the tokens on disk, ready for use when required. It
also prints a valid access token to `stdout`. From there, you can use a browser extension like
Postman or embed it in an environment variable for use in `curl`.

**To obtain an OAuth2 access token to make Edge management API calls:**

1. Download the `sso-cli` bundle:

   ```
   curl http://EDGE_SSO_IP_DNS:9099/resources/scripts/sso-cli/ssocli-bundle.zip -o "ssocli-bundle.zip"
   ```

   Where <var translate="no">EDGE_SSO_IP_DNS</var> is the IP address or DNS name of the machine hosting the
   Apigee SSO module. If you configured TLS on Apigee SSO, use `https` and the correct
   TLS port number.
2. Unzip the `ssocli-bundle.zip` bundle, as the following example shows:

   ```
   unzip ssocli-bundle.zip
   ```
3. Install `get_token` in `/usr/local/bin`, as the following example shows:

   ```
   ./install -b PATH
   ```

   The `-b` option specifies a different location.
4. Set the `SSO_LOGIN_URL` environment variable to your login URL, in the following form:

   ```
   export SSO_LOGIN_URL="http://EDGE_SSO_IP_DNS:9099"
   ```

   Where <var translate="no">EDGE_SSO_IP_DNS</var> is the IP address of the machine hosting the Apigee SSO
   module. If you configured TLS on Apigee SSO, use `https` and the correct TLS port
   number.
5. *(SAML only)* In a browser, navigate to the following URL to obtain a one-time passcode:

   ```
   http://EDGE_SSO_IP_DNS:9099/passcode
   ```

   If you configured TLS on Apigee SSO, use `https` and the correct TLS port
   number.

   > [!NOTE]
   > **Note:** If you are not currently logged in by your , you will be prompted to log in.

   This request returns a one-time passcode that remains valid until you refresh that URL to
   obtain a new passcode or you use the passcode with `get_token` to generate an
   access token.

   Note that you can use a passcode only when authenticating with a SAML IDP. You can not use
   a passcode to authenticate with an LDAP IDP.
6. Invoke `get_token` to get the OAuth2 access token, as the following example shows:

   ```
   get_token -u EMAIL_ADDRESS
   ```

   Where <var translate="no">EMAIL_ADDRESS</var> is the email address of an Edge user.

   *(SAML only)* Enter the passcode on the command line in addition to the email
   address, as the following example shows:

   ```
   get_token -u EMAIL_ADDRESS -p PASSCODE
   ```

   The `get_token` utility obtains the OAuth2 access token, prints it to the
   screen, and writes it and the refresh token to `~/.sso-cli`.
7. Pass the access token to an Edge management API call as the `Bearer` header, as the following example shows:

   ```
   curl -H "Authorization: Bearer ACCESS_TOKEN"
     https://MS_IP:8080/v1/organizations/ORG_NAME
   ```
8. After you get a new access token for the first time, you can get the access token and pass it to an API call in a single command, as the following example shows:

   ```
   header=`get_token` && curl -H "Authorization: Bearer $header"
     https://MS_IP:8080/v1/o/ORG_NAME
   ```

   With this form of the command, if the access token has expired, it is automatically
   refreshed until the refresh token expires.

(SAML only) After the refresh token expires, `get_token` prompts you for a new passcode. You
must navigate to the URL shown above in step 3 and generate a new passcode before you can generate
a new OAuth access token.

## Use the management API to get and refresh
tokens

[Use OAuth2
security with the Apigee Edge management API](https://docs.apigee.com/api-services/content/using-oauth2-security-apigee-edge-management-api) shows how to use the
Edge management API to obtain and refresh tokens. You can also use Edge API calls to get tokens
generated from SAML assertions.

The only difference between the API calls documented in
[Using OAuth2
security with the Apigee Edge management API](https://docs.apigee.com/api-services/content/using-oauth2-security-apigee-edge-management-api) is that the URL of the call must reference your
zone name. In addition, for generating the initial access token with a SAML IDP, you must include
the passcode, as shown in step 3 of the procedure above.

For authorization, pass a reserved OAuth2 client credential in the `Authorization`
header. The call prints the access and refresh tokens to the screen.

### Get an access token

*(LDAP)* Use the following API call to generate the initial access and refresh
tokens:

```
curl -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
  -H "accept: application/json;charset=utf-8" \
  -H "Authorization: Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" -X POST \
  http://EDGE_SSO_IP_DNS:9099/oauth/token -s \
  -d 'grant_type=password&username=USER_EMAIL&password=USER_PASSWORD'
```

*(SAML)* Use the following API call to generate the initial access and refresh
tokens:

```
curl -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
  -H "accept: application/json;charset=utf-8" \
  -H "Authorization: Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" -X POST \
  https://EDGE_SSO_IP_DNS:9099/oauth/token -s \
  -d 'grant_type=password&response_type=token&passcode=PASSCODE'
```

Note that authentication with a SAML IDP requires a temporary passcode, whereas an LDAP IDP
does not.

### Refresh an access token

To later refresh the access token, use the following call that includes the refresh token:

```
curl -H "Content-Type:application/x-www-form-urlencoded;charset=utf-8" \
  -H "Accept: application/json;charset=utf-8" \
  -H "Authorization: Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" -X POST \
  https://EDGE_SSO_IP_DNS:9099/oauth/token \
  -d 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN'
```

*[IDP]: Identity Provider