Apigee provides the following convenience utilities for generating and passing OAuth2 access and refresh tokens. You use these tokens to authenticate yourself in your management API calls (for the OAuth or SAML workflows):
acurl
: Constructs HTTP requests to the management API; gets access and refresh tokens; passes the access token to the management API; and refreshes the access token automatically.get_token
: Gets access and refresh tokens that you can use to call the management API.- Management API: Gets access and refresh tokens that you can use to call the management API.
Each of these utilities trades your Apigee account credentials (email address and password) for the 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 API is optional. You can implement your own schemes to generate OAuth2 access tokens and send them in your requests to the management API.
Install acurl and get_token
Apigee provides a ZIP file containing acurl
and get_token
and
an install script.
To install acurl
and get_token
:
- Create an install directory on your machine and
cd
to the directory. - Download the installation ZIP file from Apigee, as the following example shows:
curl https://login.apigee.com/resources/scripts/sso-cli/ssocli-bundle.zip -o "ssocli-bundle.zip"
- Unzip the downloaded file.
- Execute the install script, as the following example shows:
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 the current directory. - Test the installations, as the following examples show:
acurl -h
get_token -h
These commands return Help text for the utilities.
Token expiration
The tokens generated by acurl
and get_token
have the following
durations:
- Access tokens expire in 1,799 seconds (approximately 30 minutes)
- Refresh tokens expire in 84,600 seconds (approximately 24 hours)
As a result, once you have successfully run either acurl
or get_token
,
you can continue to use the tokens for about 24.5 hours. After that, you must re-enter your
password and get new tokens.
Use a one-time passcode
When you call acurl
or get_token
, you must authenticate yourself to the
utility before they will return an access token. To do this, you typically pass your Apigee
account's email address and password. However, if you do not want to use your password (for example,
if it's a corporate password), you can get a one-time code passcode and use that instead.
To get a one-time passcode:
- Enter the following URL in a browser:
https://login.apigee.com/passcode
- Log in to your Apigee account.
- Copy the 6-character passcode.
- Use
acurl
orget_token
with the-p
option and pass the passcode, as the following examples show:acurl https://api.enterprise.apigee.com/v1/organization/ahamilton-test-eval \ -u ahamilton@apigee.com:mypassw0rd -p 123456
get_token -u ahamilton@apigee.com:mypassw0rd -p 123456
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:
cat ~/.sso-cli/access_token.dat | python -m json.tool
This command displays the data file, which looks like the following:
{ "access_token": "ey42Jh..............................................z742zHiw1t6A", "expires_in": 1799, "jti": "26368300-4242-4940-aabb-0eac692476b8", "refresh_token": "ey42Jh..............................................mS42YgDEh7g", "scope": "scim.me openid password.write approvals.me oauth.approvals", "token_type": "bearer" }
Change the SSO endpoint
By default, acurl
and get_token
generate tokens by calling the SSO
service at the following location:
https://login.apigee.com
To use a different SSO endpoint, change the SSO_LOGIN_URL
environment variable in
your terminal session.