Using acurl

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

The acurl⁽¹⁾ utility provides a convenience wrapper around a standard curl command. acurl:

• Exchanges your Apigee credentials for an OAuth2 access token.
• Detects when an access token has expired, and uses the refresh token to get a fresh access token.
• Passes that token in the Authorization header of the API request.

You use access tokens to call Edge API endpoints with OAuth2, including LDAP and SAML workflows.

If you use OAuth2 to access the Edge API, but don't use acurl, then you must get an access token and add it to the header of the API request yourself. One way to get an access token is with the get_token utility.

Install acurl

Before you can use acurl, you must install it.

acurl syntax

The acurl utility uses the following syntax:

acurl API_URL -u USERNAME:PASSWORD [-m MFACODE]

or

acurl API_URL -p PASSCODE

Where:

Option	Required?	Description
API_URL	Required	The Apigee Edge API endpoint. For a complete list of endpoints, see Apigee Edge API Reference.
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 acurl 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:

acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval
acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval -u ahamilton@apigee.com
acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval -u ahamilton@apigee.com -p 424242
acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval -u ahamilton@apigee.com:mypassw0rd
acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval -u ahamilton@apigee.com:mypassw0rd -m 123456

In addition to the options shown above, acurl accepts all the curl options. For example, you can pass headers, specify the HTTP verb, add a body, and enable verbosity using standard curl options:

Option	acurl meaning	curl meaning
-u	username	username
-m	MFA code	max time (must use long form --max-time)
-p	passcode	proxy tunnel (must use long form --proxytunnel)
-v	verbose	verbose
-h	help	help (must use long form --help)

acurl -v -X POST -H 'Content-Type: application/json' \
    https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval/apiproducts/myproduct/attributes/attr \
    -u ahamilton@apigee.com -d '{"value":42}'

A successful acurl call returns results based on which Edge API endpoint you called. In addition, acurl stores both the access and refresh tokens in ~/.sso-cli.

You can continue to make calls without entering credentials (password and optional MFA, or passcode) until both the access token and the refresh token expire, as described in Token expiration.

Migrate from curl

If you are using curl, migrating to the acurl utility is straightforward and eliminates the need to manually encode credentials. Once you have downloaded and installed the utility, you can replace:

curl -u username

with:

acurl -u username

The acurl utility will encode your credentials and occasionally prompt you for the additional credentials required to obtain new token pairs.

The acurl utility can also be used to replace curl for machine users. For more information, see OAuth2 for machine users and Machine users in SAML zones.

Call acurl for the first time

The first time you call the API with acurl, you provide your Apigee credentials (the username and password of your Apigee account, or a passcode) so that acurl can exchange them for an access token and refresh token.

The following example shows an initial call with acurl to get details about an organization using the Get organization endpoint:

acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -u ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com':
[hidden input]
Enter the six-digit code (no spaces) if 'ahamilton@apigee.com' is MFA-enabled or press ENTER:
1a2b3c
{
  "createdAt" : 1491854501264,
  "createdBy" : "noreply_iops@apigee.com",
  "displayName" : "ahamilton",
  "environments" : [ "prod", "test" ],
  "lastModifiedAt" : 1491854501264,
  "lastModifiedBy" : "noreply_iops@apigee.com",
  "name" : "ahamilton",
  "properties" : {
    "property" : [ {
      "name" : "features.isSmbOrganization",
      "value" : "false"
    }, {
      "name" : "features.isCpsEnabled",
      "value" : "true"
    } ]
  },
  "type" : "trial"
}

The acurl utility gets an access token and inserts it into the call to the Edge API endpoint:

curl -H "Authorization: Bearer oauth2_access_token" ...

The access token is stored locally in ~/.sso-cli and used for subsequent calls.

After the access token expires, acurl automatically uses the refresh token to get a new access token. When the refresh token expires, acurl will prompt you for your Apigee credentials.

This request gets details about the "ahamilton-eval" organization. For a complete list of Edge API endpoints, see Apigee Edge API Reference.

---

⁽¹⁾ Copyright 2023 Google LLC
The acurl 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.

---