You're viewing **Apigee Edge** documentation.
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/system-administration/shared-vpcs). info
The `acurl`[^(1)^](https://docs.apigee.com/api-platform/system-administration/using-acurl#note1) 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](https://docs.apigee.com/api-platform/system-administration/using-oauth2-security-apigee-edge-management-api), including
LDAP and [SAML](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge) 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](https://docs.apigee.com/api-platform/system-administration/using-gettoken) utility.
## Install acurl
Before you can use `acurl`, you must
[install it](https://docs.apigee.com/api-platform/system-administration/auth-tools#install).
## 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](https://apidocs.apigee.com). |
| 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)](https://docs.apigee.com/api-platform/system-administration/enable-two-factor-auth-your-apigee-account) 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](https://docs.apigee.com/api-platform/system-administration/auth-tools#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](https://docs.apigee.com/api-platform/system-administration/auth-tools#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](https://docs.apigee.com/api-platform/system-administration/using-oauth2#oauth2-for-machine-users) and [Machine users in SAML zones](https://docs.apigee.com/api-platform/system-administration/using-saml#machine).
## 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](https://apidocs.apigee.com/docs/organizations/1/routes/organizations/%7Borg_name%7D/get) 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](https://apidocs.apigee.com).
> [!IMPORTANT]
>
> ### TIP
>
> If you receive a `404 (Not Found)` response, check that you specified the correct
> URL for the endpoint. Do not include the environment ("test" or "prod") in the name of the
> organization in your URL. For example, use ".../organizations/ahamilton-eval/...", not
> ".../organizations/ahamilton-eval**-test**/..." for the endpoint.
*** ** * ** ***
**^(1)^** 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 .
*** ** * ** ***