Using get_token

The get_token utility lets you exchange your Apigee credentials for an access and refresh token that you can then use to access Apigee management APIs. Unlike acurl, get_token simply gets and stores tokens on your disk. It's up to you to add a valid token in your requests and get a new token when yours expires.

You use access tokens to call the management API with the OAuth or SAML workflows.

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 email_address[:password] [-m mfa_code] [-p passcode]

Where:

Element Required? Description
email_address Required (first time only) The email address associated with your Apigee account. You must pass your email address in 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.
password Optional The password for your Apigee account. If you omit the password, you will be prompted to enter it. 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.
passcode Optional A one-time passcode, which you can use in place of a password.
mfa_code Optional A temporary code that you must pass to get_token if you have enabled multi-factor authentication (MFA). If you do not have MFA enabled, you can omit this option.

For example:

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

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, get_token will prompt you for your username (email address), password or passcode, and a temporary multi-factor authentication (MFA) code on your first call:

  • To use a passcode instead of a password, press ENTER when prompted for a password.
  • If you don't use MFA, press ENTER when prompted for an MFA code.

The following example calls code for the first time and uses an MFA code instead of a password for authentication:

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

ey42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJzdWIiOiIyZDFl
  <snip>
VlLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiwiYXBwcm54242

To skip entering a passcode, press ENTER when prompted for the passcode.

Add your access token to a request

After you have successfully called get_token, you can use the access token by passing it in the Authorization header of your calls to the management API. You can do this in different ways, including:

  • Copy the contents of the get_token response and insert it directly into your header:
    curl -v 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
  • 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 is surrounded by backticks (rather than single quotes) so that it is executed.

These sample requests get details about the "ahamilton-eval" organization. For a complete list of management API endpoints, see Apigee Management API Reference.

Using get_token with both OAuth2 and SAML

The get_token utility can be used in both the OAuth2 and SAML flows to get an access token and to refresh it.

However, if you use both flows, you may need to use a separate machine or get new tokens periodically. For more information, see Use OAuth2 and SAML at the same time.