Instagram — auth/getToken

Token lifecycle: The Meta OAuth flow produces a short-lived token (1-hour expiry). This node exchanges it for a long-lived token (60-day expiry). Store the long-lived token in BizFirst Credentials Manager immediately. Schedule auth/refreshToken every 50 days to prevent expiry.

When to Use

Initial OAuth setup: After a user completes the Facebook Login / Instagram OAuth flow and your redirect URI receives the short-lived code, trigger this node to exchange it for a long-lived token.
User onboarding flow: In a multi-tenant platform, each new user who connects their Instagram account goes through this step to produce the long-lived token stored against their tenant.
Token rotation policy: Some security policies require periodic full re-authentication rather than refresh. Run this node after a new OAuth flow completes to replace an expired token.
Testing and development: During development, quickly exchange test OAuth codes to long-lived tokens without writing custom HTTP request nodes.
Migration from short-lived tokens: If existing integrations use short-lived tokens, run this node once per account to upgrade to long-lived tokens for more reliable automation.

Configuration

Connection

This operation handles authentication itself — no pre-existing token is needed as an input. It produces the token.

Operation

Field	Required	Description
`resource`	Required	Must be `auth`.
`operation`	Required	Must be `exchange-token`.
`shortLivedToken`	Required	The short-lived user access token from the OAuth redirect callback. Expires in 1 hour.
`clientSecret`	Optional	Your Meta app's client secret. Not recommended for production — use `clientSecretVaultKey` instead.
`clientSecretVaultKey`	Optional	BizFirst Credentials Manager key referencing the Meta app client secret. Preferred over `clientSecret` for security. One of `clientSecret` or `clientSecretVaultKey` is required.

Secret storage: Never store the clientSecret directly in workflow configuration in production environments. Always use clientSecretVaultKey to reference a secret from the BizFirst Credentials Manager vault. Workflow configurations may be exported or logged — raw secrets in config are a security risk.

Sample Configuration JSON

{
  "resource": "auth",
  "operation": "exchange-token",
  "shortLivedToken": "{{ $trigger.body.shortLivedToken }}",
  "clientSecretVaultKey": "meta_app_client_secret"
}

Validation Errors

Error	Cause
`shortLivedToken is required`	`shortLivedToken` field is missing or empty.
`clientSecret or clientSecretVaultKey is required`	Neither secret field is provided.
Graph API error 190	The short-lived token is expired (older than 1 hour) or invalid.

Output

Success Port

Field	Type	Description
`status`	string	`"success"`
`accessToken`	string	The long-lived access token (60-day expiry). Store immediately in BizFirst Credentials Manager.
`tokenType`	string	Token type — typically `"bearer"`.
`expiresIn`	number	Seconds until expiry from time of exchange. Typically 5183944 (approx. 60 days).
`payload`	string	Raw JSON response from the Graph API.

Error Port

Field	Type	Description
`status`	string	`"error"`
`errorCode`	string	Graph API error code.
`errorMessage`	string	Error description.
`payload`	string	Raw error response.

Sample Output JSON

{
  "status": "success",
  "accessToken": "EAABsbCS4sZBwBOZBqk...(long token)",
  "tokenType": "bearer",
  "expiresIn": 5183944,
  "payload": "{\"access_token\":\"EAAB...\",\"token_type\":\"bearer\",\"expires_in\":5183944}"
}

Expression Reference

Expression	Value
`{{ $output.instagram.accessToken }}`	Long-lived access token to store
`{{ $output.instagram.expiresIn }}`	Seconds until expiry
`{{ $output.instagram.tokenType }}`	Token type string

Node Policies & GuardRails

Immediate storage: The next node after this one should always store the accessToken to BizFirst Credentials Manager. Do not pass raw tokens through workflow variables longer than necessary.
Short-lived token window: The shortLivedToken expires 1 hour after OAuth grant. If your webhook handler takes longer than 1 hour to reach this node, the exchange will fail. Build the OAuth callback handler to call this node immediately.
Client secret security: The clientSecret is a highly sensitive credential. Always use clientSecretVaultKey in production. Rotate the client secret if it was ever stored directly in workflow config.
One token per user: Each user authentication produces a unique long-lived token scoped to that user's permissions. Store tokens per-user, not as a shared global credential, in multi-tenant deployments.

Examples

OAuth callback handler — exchange and store token

// Triggered by webhook from your OAuth redirect URI
{
  "resource": "auth",
  "operation": "exchange-token",
  "shortLivedToken": "{{ $trigger.body.shortLivedToken }}",
  "clientSecretVaultKey": "meta_app_client_secret"
}
// Next node: store accessToken in Credentials Manager under key "instagram_token_{{ $trigger.body.userId }}"

New tenant onboarding flow

{
  "resource": "auth",
  "operation": "exchange-token",
  "shortLivedToken": "{{ $input.oauthToken }}",
  "clientSecretVaultKey": "{{ $env.META_SECRET_VAULT_KEY }}"
}

Part of the tenant onboarding workflow. After exchange, the accessToken is stored against the tenant ID in the Credentials Manager, and a 50-day cron job is created to refresh it before expiry.