Using the get_token and acurl utilities

Apigee provides the get_token and acurl utilities to simplify interaction with the Apigee SSO and the Edge management API. These tools handle token generation, caching, refreshing, and injection automatically.

The utilities are installed on the OpenLDAP node at /opt/apigee/apigee-openldap/bin/.

The get_token utility

The get_token utility is responsible for acquiring OIDC/OAuth2 access and refresh tokens. It supports two primary authentication flows and includes built-in token caching.

Authentication flows

  • Device Code Flow (RFC 8628): Designed for human users authenticating via an external Identity Provider (such as SAML, Okta, or OIDC). If you pass only an email address (-u <email>), the utility initiates this flow, prompting you with a URL and code to approve in a browser.
  • Password Grant (ROPC): Designed for headless machine users and automated scripts. If you pass both a username and password (-u <user>:<password>), it authenticates directly against the Apigee SSO without browser interaction.

Token caching and auto-refresh

The get_token utility automatically manages token lifecycles so you do not have to manually track expiration times:

  • Cache Check: When invoked, get_token checks the local cache at ~/.sso-cli/<username>-token.json. If a valid token exists and has not expired, it reuses the token without re-authenticating.
  • Auto-Refresh: If the cached access token has expired but a valid refresh token exists, the utility automatically exchanges the refresh token at the Apigee SSO for a fresh access token.

Environment variables

You can optionally customize the behavior of get_token using the following environment variables:

  • SSO_LOGIN_URL: The Apigee SSO URL (default: http://localhost:9099).
  • CLIENT_ID: The OAuth2 client ID (default: edgecli).
  • CLIENT_SECRET: The OAuth2 client secret (default: edgeclisecret).

The acurl utility

The acurl utility is a transparent wrapper around standard curl. It ensures that every API request includes a valid Bearer token.

  • Argument Separation: The utility extracts the -u <user:password> or -u <user> argument and passes it to get_token. It forwards all other arguments (such as -X, -H, -d, -v, -s) directly to standard curl.
  • Execution: After successfully acquiring or retrieving a valid token from get_token, acurl automatically injects the -H "Authorization: Bearer <token>" header into the curl invocation.

Usage examples

Example 1: Interactive login for a human user

/opt/apigee/apigee-openldap/bin/acurl -u developer@apigee.com http://MS_IP_DNS:8080/v1/organizations

This command pauses, prompts the user to visit a browser to authenticate via their external IDP, and then executes the API call once approved.

Example 2: Headless login for a machine user

/opt/apigee/apigee-openldap/bin/acurl -u jenkins-bot@apigee.com:Secret123! http://MS_IP_DNS:8080/v1/organizations

This command authenticates directly via Password Grant and executes the API call immediately.

Example 3: Reusing a cached token

/opt/apigee/apigee-openldap/bin/acurl http://MS_IP_DNS:8080/v1/users

Because the token was cached in the previous steps, you do not need to provide the -u argument again. The utility reads the cached token and injects it automatically.