Using get_token

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

The get_token(1) 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 and LDAP implementations of OAuth2 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.

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
USERNAME 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.
PASSWORD 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.
MFACODE Optional A temporary six-digit multi-factor authentication (MFA) 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.
PASSCODE Optional. A username and password combination or a passcode is required. A one-time 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.

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.

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 SSO_LOGIN_URL 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.