You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/troubleshoot/policies/runtime/service-callout-runtime-errors). info

The `get_token`[^(1)^](https://docs.apigee.com/api-platform/system-administration/using-gettoken#note1) utility lets you exchange your Apigee credentials for an access
and refresh token that you can use to access Edge APIs. The tokens can also be used with [SAML](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge)
and LDAP implementations of [OAuth2](https://docs.apigee.com/api-platform/system-administration/using-oauth2-security-apigee-edge-management-api) workflows.

`get_token` enables you to:

- Obtain an access or refresh token.
- Print tokens to `stdout` for use in variables and commands.
- Store tokens on your disk.

You can then add a valid token in your requests to the Edge API and get a new token when yours expires.

**Prerequisite:** Before you can use `get_token`, you must
[install it](https://docs.apigee.com/api-platform/system-administration/auth-tools#install).

## get_token syntax

The `get_token` utility uses the following syntax:

```
get_token -u USERNAME:PASSWORD [-m MFACODE]
```

or

```
get_token -p passcode
```

Where:

| Element | Required? | Description |
|---|---|---|
| <var translate="no">USERNAME</var> | **Optional. A username and password combination or a passcode is required.** | Your Apigee username, which is usually the email address associated with your Apigee account. You must pass your username or a passcode the first time you call `get_token`. You will not need to pass your email address in again until the access and refresh tokens have expired. If you are caching tokens for more than one user, you must specify your username in each call. |
| <var translate="no">PASSWORD</var> | **Optional. A username and password combination or a passcode is required.** | The password for your Apigee account. If you omit the password, you will be prompted to enter it the first time you use `get_token` and on any subsequent calls without a valid refresh token. If you do not want to use your password directly in the command, you can use a one-time code passcode instead of your password. |
| <var translate="no">MFACODE</var> | **Optional** | A temporary six-digit [multi-factor authentication (MFA)](https://docs.apigee.com/api-platform/system-administration/enable-two-factor-auth-your-apigee-account) code. This code is required if you use `-u` and have MFA enabled. You will be prompted if omitted (unless in passcode mode). If you do not have MFA enabled, or you have a scripted flow, you can specify `-m ""` to avoid prompts. |
| <var translate="no">PASSCODE</var> | **Optional. A username and password combination or a passcode is required.** | A [one-time passcode](https://docs.apigee.com/api-platform/system-administration/auth-tools#passcode) you can use in place of a password. A passcode is required when authenticating with a SAML IDP, and may be used to authenticate with an LDAP IDP. |

For example:

    get_token
    get_token -u ahamilton@apigee.com:mypassw0rd -m 424242
    get_token -p mypass

A successful call prints a valid access token to `stdout` and stores both the
access and refresh tokens in `~/.sso-cli`. You can use these tokens until they
expire, as described in [Token expiration](https://docs.apigee.com/api-platform/system-administration/auth-tools#expiration).

After your first successful call to `get_token`, you do not need to include your
credentials until the tokens have expired.

## Call get_token for the first time

If you don't specify any options in your first call, `get_token` will prompt you for
the following:

- A passcode, if authenticating with a SAML identity provider (IDP).
- Your username, password, and a temporary MFA code, otherwise.

The following example calls `get_token` for the first time and uses a
username/password combination with an optional MFA code for authentication:

    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

    ey42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJzdWIiOiIyZDFl
      <snip>
    VlLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiwiYXBwcm54242

## Add your access token to a request

After you successfully call `get_token`, you can use the access token
by passing it in the `Authorization` header of your calls to the Edge API in a number of ways.
You can:

- Copy the contents of the `get_token` response and insert it directly into your header:

  ```
  curl https://api.enterprise.apigee.com/v1/organizations/danger4242-eval \
    -H "Authorization: Bearer B42CnTIYPxr...88NI5Q"
  ```
- Combine commands to get the token and add it to the header:

  ```
  token=$(get_token); curl -H "Authorization: Bearer $token" \
    https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval
  ```

  Note that `get_token` uses command substitution syntax `$(...)` so
  that it is executed.
- Call `get_token` within the `curl` call:

  ```
  curl -H "Authorization: Bearer $(get_token)" \
    https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval
  ```

  Note that `get_token` uses command substitution syntax `$(...)` so
  that it is executed.

These sample requests get details about the "ahamilton-eval" organization. For a complete list
of Edge API endpoints, see [Apigee Edge API Reference](https://apidocs.apigee.com).

## Use get_token with SAML and LDAP

The `get_token` utility can be used with SAML, LDAP or any other underlying IDP.
`get_token` supports the use of multiple SSO login URLs and multiple accounts.
A single user with multiple accounts will be prompted to specify the username
for each `get_token` call.

## Clear the get_token cache

You can use the following optional flags to clear the `get_token` cache:

-

  ```
  --clear-sso-cache
  ```

  Clears cache directory for <var translate="no">SSO_LOGIN_URL</var> under `$HOME/.sso-cli`
  discarding any cached access and refresh tokens for the server.
-

  ```
  --clear-all-sso-cache
  ```

  Clears all directories under `$HOME/.sso-cli` discarding all cached tokens.

*** ** * ** ***

**^(1)^** Copyright 2023 Google LLC  

The `get_token` tool is made available as "Software" under the
agreement governing your use of Google Cloud Platform, including the Service
Specific Terms available at <https://cloud.google.com/terms/service-terms>.

*** ** * ** ***