Using access tokens to authenticate management API calls

Apigee Edge allows you to make management API calls that are authenticated with either Basic Authentication credentials or an access token. This topic explains how to generate and use access tokens to call the management API. These tokens are generated for you by Apigee and conform to the OAuth 2.0 Authorization Framework specification.

This topic explains how to exchange your Edge credentials for an access token and a refresh token that you can use to authenticate management API calls. Once you obtain an access token, you do not need to exchange your credentials again until the token expires. The refresh token allows you to keep your "session" with the server alive for a longer period without providing your credentials again.

About the access token scripts

Apigee provides two scripts that you can install and use to get access tokens and make management API calls.

  • acurl: Allows you to use your existing cURL-based scripts that make management API calls. This script retrieves an access token from Apigee and then makes a cURL call with the proper Authorization header that contains the access token. When the access token expires, acurl gets a new one using the refresh token. Note that both the access and refresh tokens are stored locally, and the acurl script accesses them to do its work.
  • get_token: Exchanges your Apigee credentials for an access and refresh token that can be used to authenticate Edge management APIs directly. If an access token can be refreshed, the script will refresh it and save the new token. If the refresh token expires, the script will prompt for your user credentials. Note that the script stores the tokens on disk, ready for use when required, and it also prints a valid access token to stdout. Once you obtain a valid token, you can use a REST client like Postman or embed the token in an environment variable for use in cURL.

Installing the acurl and get_token scripts

Apigee provides a ZIP file containing acurl and get_token and an install script.

  1. Create an install directory on your machine and cd to the directory.
  2. Download the installation ZIP file from Apigee as follows:
    curl https://login.apigee.com/resources/scripts/sso-cli/ssocli-bundle.zip -o "ssocli-bundle.zip"
  3. Unzip the downloaded file.
  4. Run the install script. Optionally, use the -b option to specify the location of the executable files. Otherwise, they will be placed in the current directory.
    sudo ./install -b /usr/local/bin
  5. Test the installations as follows. These commands print help information.
    acurl -h
    get_token -h

Using acurl

acurl exchanges your Apigee user credentials for an access and refresh token. The script automatically uses the refresh token to get a new access token when it expires. When the refresh token expires, acurl will fail and prompt you for your Apigee credentials. acurl wraps a standard cURL command that includes the access token in an Authorization header automatically for you, like this:

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

First use or after refresh token expiration

The first time you call acurl, you need to provide your Apigee credentials so that acurl can exchange them for an access token and refresh token. You will not need to use your Apigee credentials again, until the refresh token has expired.

  1. Be sure you have successfully installed acurl as explained previously.
  2. Make Apigee Edge management API calls as follows, where username is the email address associated with your Apigee account:
    acurl https://api.enterprise.apigee.com/v1/o/orgname -u username:password \
      -m one_time_MFA_code

    where:

    • orgname: The name of your Apigee organization.
    • username: The email address associated with your Apigee account.
    • password: Your Apigee password.
    • one_time_MFA_code: The one-time code generated for you if you have multi-factor authentication (MFA) enabled. If you do not have MFA enabled, you can omit this parameter.

Example:

acurl https://api.enterprise.apigee.com/v1/o/docs -u jdoe@apigee.com -m 567123
Enter the password for user 'jdoe@apigee.com
password
{
  "createdAt" : 1491854501264,
  "createdBy" : "noreply_iops@apigee.com",
  "displayName" : "jdoe",
  "environments" : [ "prod", "test" ],
  "lastModifiedAt" : 1491854501264,
  "lastModifiedBy" : "noreply_iops@apigee.com",
  "name" : "jdoe",
  "properties" : {
    "property" : [ {
      "name" : "features.isSmbOrganization",
      "value" : "false"
    }, {
      "name" : "features.isCpsEnabled",
      "value" : "true"
    } ]
  },
  "type" : "trial"
}

Using get_token

The get_token utility lets you exchange your Apigee credentials for an access and refresh token that you can then use to access Apigee management APIs. Unlike with the acurl command, get_token simply gets and stores tokens on your disk. It is up to you to place a valid token in the Authorization header of your management API calls. Usage examples are provided below.

  1. Be sure you have successfully installed get_token as explained previously.
  2. If it does not exist already, create the directory ~/.sso-cli. The get_token script stores newly minted tokens in this directory.
  3. The simplest way to use get_token from the command line is to call the script and let it prompt you for input, where jdoe@apigee.com is an Apigee account username (normally, this is your Apigee account email address):
    get_token
    Enter username: jdoe@abc123.com
    Enter the password for user 'jdoe@apigee.com'
    Enter the six-digit code if 'jdoe@apigee.com' is MFA enabled or press ENTER: your_six_digit_code
  • If you do not use multi-factor authentication (the six-digit code), just hit Enter when prompted.
  • If you do not enter your username within 30 seconds, the script times out and exits with a non-zero error.
  • A successful call prints a valid access token to stdout and stores the tokens in ~/.sso-cli.

Alternative usage

You can also use get_token by providing the required parameters directly in the command as follows:

get_token -u your_Apigee_email_address:your_Apigee_password \
  -m your_six_digit_code

Examples

get_token -u jdoe@apigee.com:abc123 -m 567123 eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI4NjI5ZDVlZC1lMGY0LTQ3YWYtOTIwNS1kNWRiOWI2YTk3MDgiLCJzdWIiOiI3NWFlYjg0Ni1lYjMwLTQ3YTMtOTg0ZC1kZjNhZDg2NTg1MGQiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwicGFzc3dvcmQud3JpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5RpbWUiOjE1MTQ4hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsImNpZCI6ImVkZ2VjbGkiLCJhwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6Ijc1YWViODQ2LWViMzAtNDdhMy05ODRkLWRmM2FkODY1ODUwZCIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoid2lsbHdpdG1hbkBnb29nbGUuY29tIiwiZW1haWwiOiJ3aWxsd2l0bWFuQGdvb2dsZS5jb20iLCJhdXRoX3NDk4NzEsImFsIjoyLCJyZXZfc2lnIjoiZmY1ODgwMGYiLCJpYXQiOjE1MTQ4NDk4NzEsImV4cCI6MTUxNDg1MTY3MSwiaXNzIjoiaHR0cHM6Ly9sb2dpbi5hcGlnZWUuY29tIiwiemlkIjoidWFhIiwiYXVkIjpbImVkZ2VjbGkiLCJzY2ltIiwib3BlbmlkIiwienAiOiJlZGdlY2xpIicGFzc3dvcmQiLCJhcHByb3ZhbHMiLCJvYXV0aCJdfQ.bWj31E3jwl6IwPW6sIFKeqH1_IVMVFpWLXBImNmps2iOeIWyktZO3u0mANvXpmr313mB6j6qAbiFgwCG2WfbXQkH_TbmBpVMgrYwHWqv90fOkNvbJFUnx--ChhypUusHFx3w6InjVwcG85juGq9REJgtSfaFRjb5l5TNtn6_p9wDyQyvM84uw2NmEcJA-FLi-L9EBKaseX6MZWj8gwpxEiXO3XE3N6veaOV344JjzPtKbUZ3mGtIEpkwkcFooqWOLiLs22IwFIdMc8aEcbe_R3AXe1ot-vJwVEspn3p0XqNlAA4_iQolZTrCLjoQADaE6IrR9Kt-kLehSk4GnNwR7g

You can use the token by placing it directly in the Authorization header of a management API call. For example:

curl -H "Authorization: Bearer your_token" \
  -v https://api.enterprise.apigee.com/v1/o/your_organization

After you have generated tokens successfully (that is, after you have run get_token for the first time), you can embed get_token directly in a cURL call as follows. With this technique, the get_token command will handle refreshing an expired token automatically (until the refresh token expires).

header='get_token' && curl -H "Authorization: Bearer $header" \
  -v https://api.enterprise.apigee.com/v1/o/your_organization

Obtaining and using a one-time passcode

If you do not want to use your password in the acurl command (for example, if it is a corporate password), you can obtain a one-time code passcode to use instead of your password.

  1. Enter this URL in a browser: https://login.apigee.com/passcode
  2. Log into your Apigee account.
  3. Copy the 6-character passcode.
  4. Call acurl as follows:
    acurl https://api.enterprise.apigee.com/v1/o/orgname -u username \
      -m one_time_MFA_code -p your_passcode

    For example:

    acurl https://api.enterprise.apigee.com/v1/o/docs -u jdoe@apigee.com -m 567123 -p Tg8Xx0
    {
      "createdAt" : 1491854501264,
      "createdBy" : "noreply_iops@apigee.com",
      "displayName" : "jdoe",
      "environments" : [ "prod", "test" ],
      "lastModifiedAt" : 1491854501264,
      "lastModifiedBy" : "noreply_iops@apigee.com",
      "name" : "jdoe",
      "properties" : {
        "property" : [ {
          "name" : "features.isSmbOrganization",
          "value" : "false"
        }, {
          "name" : "features.isCpsEnabled",
          "value" : "true"
        } ]
      },
      "type" : "trial"
    }

Using get_token to obtain access tokens from SAML assertions

Edge supports Security Assertion Markup Language (SAML) 2.0 as the authentication mechanism. SAML provides support for a single sign-on (SSO) environment. By using SAML with Edge, you can support SSO for the Edge UI and API in addition to any other of your services that support SAML.

After you enable SAML, Basic Auth is disabled for the Edge management API. You must update any API calls and scripts that use Basic Auth to use OAuth2 bearer tokens instead. To do so, use get_token to exchange your SAML assertion for an OAuth2 bearer token usable by the Edge management API. You then pass that access token as the Bearer header to make Edge management API calls. For example:

curl -H "Authorization: Bearer access_token" \
  https://api.enterprise.apigee.com/v1/organization/orgName

For more information on generating and using tokens for Edge SSO, including using tokens with the Edge UI and API, see Enabling SAML Authentication for Edge.

Using the API to get tokens

You can get access and refresh tokens using the API, as explained in this section.

(POST) Get a new access token

Use this API to get a new access token. In the output, you will receive both an access token and a refresh token. If you save the refresh token, you can make subsequent API calls to obtain new access tokens (see Refresh an access token).

Request URL

https://login.apigee.com/oauth/token

Header parameters

Parameter Value
Content-Type application/x-www-form-urlencoded
Accept application/json;charset=utf-8
Authorization Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0

Form parameters (x-www-form-urlencoded)

Parameter Value
username YOUR_APIGEE_ACCOUNT_EMAIL_ADDRESS
password YOUR_APIGEE_ACCOUNT_PASSWORD
grant_type password
mfa_token A valid multi-factor auth token for your account. Required only if you have multi-factor auth (MFA) enabled on your Apigee account. See also Enable two-factor auth for your Apigee account.

Example using MFA token

curl -H "Content-Type:application/x-www-form-urlencoded;charset=utf-8" \
  -H "Accept: application/json;charset=utf-8" \
  -H "Authorization: Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" \
  -X POST https://login.apigee.com/oauth/token?mfa_token=6_digit_token \
  -d 'username=jdoe@example.com&password=abc123&grant_type=password'

Output

On success, you will get back an access token, refresh token, and related information. For example:

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOimYyD8IP2IyYS1jNmNiLTQ4NTgtYjZkMS1mZjkyNGFkYTk1YWUiLCJzdWIiOiI0X0KLSNjZlNjM0ZC0zZjlhLTRiNYmFjNi1kYjE2M2M5OGEzOGYiLCJzY29wZSI6WyJzYbmlkIiwicGFzc3dvcmQud3JpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsImNpZCI6ImVkZ2VjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjQ2NmU2MzRkLTNmOWEtNGI0MS1iYWM2LWRiMTYzYzk4YTM4ZiIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoid3dpdG1hbkBhcGlnZWUuY29tIiwiZW1haWwiOiJ3d2l0bWFuQGFwaWdlZS5jb20iLCJhdXRoX3RpbWUiOjE0NzMyNjU4NzcsImFsIjoyLCJyZXZfc2lnIjoiZTc0ZGY0M2QiLCJpYXQiOjE0NzMyNjU4NzcsImV4cCI6MTQ3MzI2NzY3NywiaXNzIjoiaHR0cHM6Ly9sb2dpbi5hcGlnZWUuY29tL29hdXRoL3Rva2VuIiwiemlkIjoidWFhIiwi2ltLm1lIiwib3BlYXVkIjpbImVkZ2VjbGkiLCJzY2ltIiwib3BlbmlkIiwicGFzc3dvcmQiLCJhcHByb3ZhbHMiLCJvYXV0aCJdfQ.AFuevkeGGUGSPED8leyEKaT-xg1xk_VEiKJLEpipVvQBXIqEc9wqcpm-ZuoatA9DhjASRuFSRaHH8Fasx_vBxEBsUNhRY-GTMw7_8fv4yRMOb2AO3WUl_NWwPkC8XRSI1zCMbAZicojsJ1n3OSP487Mu9dl9ByX5A_QfHV2_cj4l9-SD7u6vOdfdbBxbNMAQkfZLrVIEU8myF2dhKnNeMiuoHSHANsQFcx0_BFA1HnSUnVi4RYj1FlTs9SbcPnS1d7t7eVdxWz_q2OFVXNIBMELAvvM0WhXPYTW3Osve3UvvUs6ekGs-K-RCPSok-4-NJbdCDpZQQTgqHsrf77NTsw",
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJmZTIIMZWI0ZS00YzFmLTRjOTEtYmY5Mi1mMzZLEMzNjZhMDctciIsInN1YiI6IjQ2NmU2MzRkLTNmOWEtNGI0MS1iY17LLWRiMTYzYzk4YTM4ZiIsInNjb3BlIjpbInNjaW0ubWUiLCJvcGVuaWQiLCJwYXNzd29yZC53cml0ZSIsImFwcHJvdmFscy5tZSIsIm9hdXRoLmFwcHJvdmFscyJdLCJpYXQiOjE0NzMyNjU4NzcsImV4cCI6MTQ3NsaSIsImNsaWVudF9pZCI6ImVkZ2VjbGkiLCJpc3MiOiJodHRwczovL2xvZ2luLmFwaWdlZS5jb20vb2F1dGgvdG9rZW4iLCJ6aWQiOiJ1YWEiLCJncmFudF90eXBlIjoicGFzc3dvcmQiLCJ1c2VyX25hbWUiOiJ3d2l0bWFuQGFwaWdlZS5jbMzM1MDQ3NywiY2lkIjoiZWRnZW20iLCJvcmlnaW4iOiJ1c2VyZ3JpZCIsInVzZXJfaWQiOiI0NjZlNjM0ZC0zZjlhLTRiNDEtYmFjNi1kYjE2M2M5OGEzOGYiLCJhbCI6MiwicmV2X3NpZyI6ImU3NGRmNDNkIiwiYXVkIjpbImVkZ2VjbGkiLCJzY2ltIiwib3BlbmlkIiwicGFzc3dvcmQiLCJhcHByb3ZhbHMiLCJvYXV0aCJdfQ.kBP5AkbRS7Tnp-5VAfTLVfkUbUer4gFEU6A7g202KTKiXbqTwPSmOIGFTK12XevVPQYmAaSMFAnempWKfY7sjaY7HC7q3mGl53_A18cnkKhtNq15wCnyMom_bX_MYLW1RQPFytJ6akSJ-JkoPFU0x_FQg1JIvub1A8eqQxcR0KP-QRCxYAS4HTjH80vDIxHNt1tg7clmpa3RlHri0dlPVVsSpTXXhkpXRg5QbiWMrpkACSV22c0x0KiNu7vx5A520VOCO7hQ7IzmVIcSWcRqI97L7WdCjH_q4105bs2qmW73670MC0UGiJ9t5B1S1cxwqpUEd-NAuCsY8SVn6eWzbA",
  "expires_in": 1799,
  "scope": "scim.me openid password.write approvals.me oauth.approvals",
  "jti": "9bf2cb2a-c6cb-4858-b6d1-ff924ada95ae"
}

(POST) Refresh an access token

Use this API to get a access token with a refresh token. You'll get back a new access token and refresh token. Save the refresh token to make subequent calls to get a new access token.

Request URL

https://login.apigee.com/oauth/token

Header parameters

Parameter Value
Content-Type application/x-www-form-urlencoded
Accept application/json;charset=utf-8
Authorization Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0

Form parameters (x-www-form-urlencoded)

Parameter Value
refresh_token YOUR_REFRESH_TOKEN
grant_type refresh_token

Example

curl -H "Content-Type:application/x-www-form-urlencoded;charset=utf-8"
  -H "Accept: application/json;charset=utf-8" \
  -H "Authorization: Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" \
  -X POST https://login.apigee.com/oauth/token \
  -d 'grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN'

Output

On success, you will get back a new access token, refresh token, and related information. For example:

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOimYyD8IP2IyYS1jNmNiLTQ4NTgtYjZkMS1mZjkyNGFkYTk1YWUiLCJzdWIiOiI0X0KLSNjZlNjM0ZC0zZjlhLTRiNYmFjNi1kYjE2M2M5OGEzOGYiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwicGFzc3dvcmQud3JpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNUuY29tL29hdXRoL3Rva2VuIisaSIsImNpZCI6ImVkZ2VjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjQ2NmU2MzRkLTNmOWEtNGI0MS1iYWM2LWRiMTYzYzk4YTM4ZiIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoid3dpdG1hbkBhcGlnZWUuY29tIiwiZW1haWwiOiJ3d2l0bWFuQGFwaWdlZS5jb20iLCJhdXRoX3RpbWUiOjE0NzMyNjU4NzcsImFsIjoyLCJyZXZfc2lnIjoiZTc0ZGY0M2QiLCJpYXQiOjE0NzMyNjU4NzcsImV4cCI6MTQ3MzI2NzY3NywiaXNzIjoiaHR0cHM6Ly9sb2dpbi5hcGlnZWwiemlkIjoidWFhIiwiYXVkIjpbImVkZ2VjbGkiLCJzY2ltIiwib3BlbmlkIiwicGFzc3dvcmQiLCJhcHByb3ZhbHMiLCJvYXV0aCJdfQ.AFuevkeGGUGSPED8leyEKaT-xg1xk_VEiKJLEpipVvQBXIqEc9wqcpm-ZuoatA9DhjASRuFSRaHH8Fasx_vBxEBsUNhRY-GTMw7_8fv4yRMOb2AO3WUl_NWwPkC8XRSI1zCMbAZicojsJ1n3OSP487Mu9dl9ByX5A_QfHV2_cj4l9-SD7u6vOdfdbBxbNMAQkfZLrVIEU8myF2dhKnNeMiuoHSHANsQFcx0_BFA1HnSUnVi4RYj1FlTs9SbcPnS1d7t7eVdxWz_q2OFVXNIBMELAvvM0WhXPYTW3Osve3UvvUs6ekGs-K-RCPSok-4-NJbdCDpZQQTgqHsrf77NTsw",
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJmZTIIMZWI0ZS00YzFmLTRjOTEtYmY5Mi1mMzZLEMzNjZhMDctciIsInN1YiI6IjQ2NmU2MzRkLTNmOWEtNGI0MS1iY17LLWRiMTYzYzk4YTM4ZiIsInNjb3BlIjpbInNjaW0ubWUiLCJvcGVuaWQiLCJwYXNzd29yZC53cml0ZSIsImFwcHJvdmFscy5tZSIsIm9hdXRoLmFwcHJvdmFscyJdLCJpYXQiOjE0NzMyNjU4NzcsImV4cCI6MTQ3MzM1MDQ3NywiY2lkIjoiZWRnZWNsaSIsImNsaWVudF9pZCI6ImVkZ2VjbGkiLCJpc3MiOiJodHRwczovL2xvZ2luLmFwaWdlZS5jb20vb2F1dGgvdG9rZW4iLCJ6aWQiOiJFudF90eLCJ1c2VyX25hbWUiOiJ3d2l0bWFuQGFwaWdlZS5jb20iLCJvcmlnaW4iOiJ1c2VyZ3JpZCIsInVzZXJfaWQiOiI0NjZlNjM0ZC0zZjlhLTRiNDEtYmFjNi1kYjE2M2M5OGEzOGYiLCJhbCI6MiwicmV2X3NpZyI6ImU3NGRmND1YWEiLCJncmNkIiwiYXVkIjpbImVkZ2VjbGkiLCJzY2ltIiwib3BlbmlkIiwicGFzc3dvcmQiLCJhcHByb3ZhbHMiLCJvYXV0aCJdfQ.kBP5AkbRS7Tnp-5VAfTLVfkUbUer4gFEUXBlIjoicGFzc3dvcmQi6A7g202KTKiXbqTwPSmOIGFTK12XevVPQYmAaSMFAnempWKfY7sjaY7HC7q3mGl53_A18cnkKhtNq15wCnyMom_bX_MYLW1RQPFytJ6akSJ-JkoPFU0x_FQg1JIvub1A8eqQxcR0KP-QRCxYAS4HTjH80vDIxHNt1tg7clmpa3RlHri0dlPVVsSpTXXhkpXRg5QbiWMrpkACW73670MCSV22c0x0KiNu7GiJ9t5B1S1cxwvx5A520VOCO7hQ7IzmVIcSWcRqI97L7WdCjH_q4105bs2qm0UqpUEd-NAuCsY8SVn6eWzbA",
  "expires_in": 1799,
  "scope": "scim.me openid password.write approvals.me oauth.approvals",
  "jti": "9bf2cb2a-c6cb-4858-b6d1-ff924ada95ae"
}

Usage notes

  • Both acurl and get_token scripts hit the SSO endpoint specified in the SSO_LOGIN_URL environment variable. The default endpoint is https://login.apigee.com.
  • Access tokens expire in 1799 seconds (approximately 30 minutes).
  • Refresh tokens expire in 84600 seconds (approximately 24 hours).

Enabling 2-factor security

You can optionally enable 2-factor security for your Apigee Edge account. When 2-factor security is enabled, you provide a randomly generated number along with your user credentials when logging into your Apigee account. See also Enable two-factor auth for your Apigee account. At this time, you can use acurl to make calls whether or not you have 2-factor security enabled.

Send feedback about...

Apigee Docs