Using acurl

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

  • Exchanges your Apigee credentials for an OAuth2 access token
  • Passes that token in the Authorization header of the API request
  • Detects when an access token has expired, and sends the refresh token

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

Prerequisite: Before you can use acurl, you must install it.

If you use OAuth2 to access the management 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.

acurl syntax

The acurl utility uses the following syntax:

acurl management_API_endpoint -u email_address[:password] [-p passcode] [-m mfa_code]

Where:

Option Required? Description
management_API_endpoint Required The management API endpoint. For a complete list of endpoints, see Apigee Management API Reference.
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 acurl. On subsequent calls, your access token authenticates you. 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 on your first acurl call. If you do not want to use your password directly in the command, you can use a oneone-time passcode instead of your password.
passcode Optional A one-time passcode that you can use isntead of a password.
mfa_code Optional A temporary code that you must pass to acurl if you have enabled multi-factor authentication (MFA). If you do not have MFA enabled, you can omit this option.

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
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 management 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 a password until both the access token and the refresh token expire, as described in Token expiration.

Call acurl for the first time

The first time you call acurl, you need to provide your Apigee credentials (your email address and password associated with your Apigee account) so that acurl can exchange them for an access token and refresh token. You don't have to use your Apigee credentials again until the refresh token has expired.

The following example shows the first call to acurl that gets 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
mypassw0rd
{
  "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 management API endpoint:

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

acurl stores the access token locally in ~/.sso-cli, and uses it 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 fail and prompt you for your Apigee credentials.

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