You're viewing **Apigee Edge** documentation. [Go to the **Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/reference/pay-as-you-go). info 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](https://docs.apigee.com/api-platform/system-administration/using-oauth2-security-apigee-edge-management-api) (including [SAML](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge) and LDAP workflows): - [`acurl`](https://docs.apigee.com/api-platform/system-administration/using-acurl)[^(1)^](https://docs.apigee.com/api-platform/system-administration/auth-tools#note1): 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`](https://docs.apigee.com/api-platform/system-administration/using-gettoken)[^(1)^](https://docs.apigee.com/api-platform/system-administration/auth-tools#note1): 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](https://tools.ietf.org/html/rfc6749). 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`[^(1)^](https://docs.apigee.com/api-platform/system-administration/auth-tools#note1), `get_token`[^(1)^](https://docs.apigee.com/api-platform/system-administration/auth-tools#note1), and an install script. > [!NOTE] > **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)](https://docs.microsoft.com/en-us/windows/wsl/install-win10) in order to install and run these tools. **To install `acurl` and `get_token`:** 1. Create an install directory on your machine or use the default `usr/local/bin` directory. 2. Download the installation ZIP file from Apigee: ``` curl https://login.apigee.com/resources/scripts/sso-cli/ssocli-bundle.zip -O ``` 3. Unzip the downloaded file. 4. 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`. 5. 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. > [!NOTE] > **NOTE:** A passcode is required if you authenticate with a SAML . You can use a passcode with an LDAP IDP if using SSO. A passcode cannot be used with an [external authentication LDAP service](https://docs.apigee.com/private-cloud/v4.50.00/external-authentication-configuration-overview) for Apigee Edge for Private Cloud. **To get a one-time passcode:** 1. 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. 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 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 ``` *** ** * ** *** **^(1)^** Copyright 2023 Google LLC The `acurl` and `get_token` tools are made available as "Software" under the agreement governing your use of Google Cloud Platform, including the Service Specific Terms available at . *** ** * ** *** *[IDP]: Identity Provider