CrabGlamp

Fetch a fresh access token from an Agent

Use the on-VM CLI or call the API directly from inside an Agent to get a current access token for a connected OAuth provider. This guide covers the CLI command, the underlying API endpoint, the response shape, the error responses (410 and 503) and how to handle each, and idiomatic patterns for using the returned token in shell scripts.

Last updated:

Your Agent needs to call a Google, GitHub, or Spotify API. The proxy holds the refresh token; you fetch a current access token on demand.

Via the CLI

crabglamp apps google
# Writes the current access token to $GOG_ACCESS_TOKEN (in ~/.crabglamp/apps.env)

curl -s -H "Authorization: Bearer $GOG_ACCESS_TOKEN" \
  "https://www.googleapis.com/oauth2/v3/userinfo"

crabglamp apps <provider> configures the connection on the Agent and writes the access token to a provider env var — $GOG_ACCESS_TOKEN for Google, $GH_TOKEN for GitHub, $SPOTIFY_ACCESS_TOKEN for Spotify — sourced by your shell. When a token expires, crabglamp apps refresh <provider> fetches a fresh one and updates the env var.

Via the API

If you are building a non-CLI client (Python script, Go program), call the API directly with the Agent's HMAC token:

curl -s -H "authorization: Bearer $CG_HMAC_TOKEN" \
  "https://crabglamp.com/api/apps/{connection-id}/token"

Response:

{
  "accessToken": "ya29...",
  "expiresAt": "2026-05-15T14:00:00Z",
  "scopes": ["openid", "email", "profile", "https://www.googleapis.com/auth/drive.file"]
}

Error responses

The endpoint returns one of two errors (see OAuth and token storage for the reasoning):

  • HTTP 410 Gone — body { "error": "connection_error" }. The refresh token is dead at the provider; the connection is marked errored. Re-authorize from the dashboard.
  • HTTP 503 — body { "error": "refresh_unavailable" }. A transient provider error or a platform-side OAuth misconfiguration; the connection stays active. Retry with backoff. If every connection for a provider 503s, it is likely on our side — contact security@crabglamp.com.

Caching access tokens

Tokens are about 1 hour for Google and Spotify; GitHub tokens are long-lived and are not refreshed. CrabGlamp caches per connection and refreshes only when the token is within 5 minutes of expiring, so frequent calls return the same cached token without hitting the provider's token endpoint.

Related

View as Markdown — the same content as plain text for AI assistants and offline reading.

Was this helpful?