About acurl and get_token

Apigee provides the following convenience utilities for generating and passing OAuth2 access and refresh tokens. You use these tokens to authenticate yourself in your management API calls (for the OAuth or SAML workflows):

• acurl: Constructs HTTP requests to the management API; gets access and refresh tokens; passes the access token to the management API; and refreshes the access token automatically.
• get_token: Gets access and refresh tokens that you can use to call the management API.
• Management API: Gets access and refresh tokens that you can use to call the management API.

Each of these utilities trades your Apigee account credentials (email address and password) for the OAuth2 tokens.

The tokens created by the Apigee utilities conform to the OAuth 2.0 Authorization Framework specification.

Using the Apigee utilities to get tokens or access the API is optional. You can implement your own schemes to generate OAuth2 access tokens and send them in your requests to the management API.

Install acurl and get_token

Apigee provides a ZIP file containing acurl and get_token and an install script.

To install acurl and get_token:

1. Create an install directory on your machine and cd to the directory.
2. Download the installation ZIP file from Apigee, as the following example shows:

   curl https://login.apigee.com/resources/scripts/sso-cli/ssocli-bundle.zip -o "ssocli-bundle.zip"

3. Unzip the downloaded file.
4. Execute the install script, as the following example shows:

   sudo ./install -b /usr/local/bin

   The -b option specifies the location of the executable files. If you do not specify this option, the install script installs the utilities in /usr/local/bin.

5. Test the installations, as the following examples show:

   acurl -h
   get_token -h

   These commands return Help text for the utilities.

Token expiration

The tokens generated by acurl and get_token have the following durations:

• Access tokens expire in 1,799 seconds (approximately 30 minutes)
• Refresh tokens expire in 84,600 seconds (approximately 24 hours)

As a result, once you have successfully run either acurl or get_token, you can continue to use the tokens for about 24.5 hours. After that, you must re-enter your password and get new tokens.

Use a one-time passcode (SAML only)

When you call acurl or get_token, you must authenticate yourself to the utility before they will return an access token. To do this, you typically pass your Apigee account's email address and password. However, if you do not want to use your password (for example, if it's a corporate password), you can get a one-time code passcode and use that instead.

To get a one-time passcode:

1. Enter the following URL in a browser: https://login.apigee.com/passcode
2. Log in to your Apigee account.
3. Copy the 6-character passcode.
4. Use acurl or get_token with the -p option and pass the passcode, as the following examples show:

   acurl https://api.enterprise.apigee.com/v1/organization/ahamilton-test-eval \
     -u ahamilton@apigee.com:mypassw0rd -p 123456
   
   get_token -u ahamilton@apigee.com:mypassw0rd -p 123456

View your tokens

When you successfully execute acurl or get_token, the utilities create a data file in ~/.sso-cli that contains the tokens and other metadata.

To view the tokens, you can use a command like the following:

cat ~/.sso-cli/access_token.dat | python -m json.tool

This command displays the data file, which looks like the following:

{
    "access_token": "ey42Jh..............................................z742zHiw1t6A",
    "expires_in": 1799,
    "jti": "26368300-4242-4940-aabb-0eac692476b8",
    "refresh_token": "ey42Jh..............................................mS42YgDEh7g",
    "scope": "scim.me openid password.write approvals.me oauth.approvals",
    "token_type": "bearer"
}

Change the SSO endpoint

By default, acurl and get_token generate tokens by calling the SSO service at the following location:

https://login.apigee.com

To use a different SSO endpoint, change the SSO_LOGIN_URL environment variable in your terminal session.