About acurl and get_token

You're viewing Apigee Edge documentation.
View Apigee X documentation.

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

acurl: Provides a convenience wrapper around a standard curl command. Constructs HTTP requests to the Edge API, gets access and refresh tokens from get_token, and passes the access token to the Edge API.
get_token: Exchanges your Apigee credentials for access and refresh tokens that you can use to call the Edge API.

Both of these utilities trade your Apigee account credentials (username and password, or passcode) for 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 authentication server for the Edge APIs is optional. You can implement your own schemes to generate OAuth2 access tokens and send them in your requests to the Edge API.

Install acurl and get_token

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

Note: The acurl and get_token utilities are bash scripts. If you are using Windows, you will need to install Windows Subsystem for Linux (WSL) in order to install and run these tools.

To install acurl and get_token:

Create an install directory on your machine or use the default usr/local/bin directory.

Download the installation ZIP file from Apigee:

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

Unzip the downloaded file.
Execute the install script:
```
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.
Test the installations:
```
    acurl -h
    get_token -h
```
If the install is successful, these commands return Help text for the utilities.

Token expiration

acurl and get_token generate tokens with the following durations:

Access tokens expire in 12 hours.
Refresh tokens expire in 30 days.

As a result, once you have successfully made an API call with acurl or get_token, you can continue to use the token pair for 30 days. After expiration, you must re-enter your credentials and get new tokens.

Set the SSO endpoint

Before making your first call, you must set the authorization server endpoint for the Edge API you want to use with acurl and get_token.

From the terminal, set the SSO_LOGIN_URL environment variable to your authorization server endpoint. For example:

For Cloud customers without zone:

export SSO_LOGIN_URL=https://login.apigee.com

For Cloud customers with zone:

export SSO_LOGIN_URL=https://zone_name.login.apigee.com

For Private Cloud customers, contact your administrator for the appropriate SSO endpoint.

Use a one-time passcode (required for SAML)

When you make an API call with acurl or get_token, you must authenticate yourself to the utility to receive a token pair. You can do this by passing in your Apigee account's username, password, and an MFA code. However, if you are using a SAML IDP or you do not want to use your password, you can get a one-time code passcode to use instead.

To get a one-time passcode:

Enter the following URL in a browser:
- For Cloud customers without zone:
```
https://login.apigee.com/passcode
```
- For Cloud customers with zone:
```
https://zone_name.login.apigee.com/passcode
```
- For Private Cloud customers, contact your administrator for the appropriate SSO endpoint.
Log in to your Apigee account.
Copy the 6-character passcode.
Use acurl or get_token with the -p option and pass the passcode, as in the following example:
```
get_token -p 1a2b3c
```

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:

get_token -v

This command displays the decoded token claims, for example:

Decoded token claims:
 {
  "jti": "8018507e-9f34-4a90-bf97-ff226a06b19b",
  "sub": "858217a9-01a1-4111-8525-75ca555f5d5c",
  "scope": [
    "scim.emails.read",
    "scim.me",
    "openid",
    "password.write",
    "approvals.me",
    "scim.ids.read",
    "oauth.approvals"
          ],
  "client_id": "edgecli",
  "cid": "edgecli",
  "azp": "edgecli",
  "grant_type": "password",
  "user_id": "858217a9-01a1-4111-8525-75ca555f5d5c",
  "origin": "usergrid",
  "user_name": "myusername@google.com",
  "email": "myusername@google.com",
  "auth_time": 1597444772,
  "al": 0,
  "rev_sig": "6271c527",
  "iat": 1597444772,
  "exp": 1597487972,
  "iss": "https://login.apigee.com",
  "zid": "uaa",
  "aud": [
    "edgecli",
    "scim.emails",
    "scim",
    "openid",
    "password",
    "approvals",
    "scim.ids",
    "oauth"
        ]
    }
Current timestamp: 1597444983
Existing access token is still valid