Authentication — API Keys & OAuth

Register Your Application

Go to Dashboard → Settings → OAuth Applications and click Register New Application. Provide these details:

• Application Name: e.g., "PixelForge Design Tool"
• Redirect URI: e.g., https://pixelforge.design/callback/iconflow
• Scopes: Select only the permissions your app needs

After registration, you'll receive a Client ID (e.g., cf_9aB3dE7fGh2iJk). This identifier is public-safe and can be embedded in client-side code.

Authorization Request

Redirect the user to IconFlow's authorization endpoint. Include your client ID, redirect URI, a cryptographically random code_challenge, and the requested scopes.

https://auth.iconflow.dev/oauth/authorize?
  response_type=code&
  client_id=cf_9aB3dE7fGh2iJk&
  redirect_uri=https://pixelforge.design/callback/iconflow&
  scope=packs:read+downloads:read&
  state=xL8mQ2pR5tY9wN&
  code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&
  code_challenge_method=S256

Exchange Authorization Code for Token

After the user authorizes your application, IconFlow redirects back to your redirect URI with an authorization code. Exchange this code for an access token by making a server-to-server POST request:

curl -X POST "https://auth.iconflow.dev/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=cf_9aB3dE7fGh2iJk" \
  -d "code=AUTH_CODE_FROM_REDIRECT" \
  -d "redirect_uri=https://pixelforge.design/callback/iconflow" \
  -d "code_verifier=D2o1jQ8n7K3mR5pT9wL4xY6zA0bC"

// Response:
{
  "access_token": "iat_eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "irt_8xK2mN9pQr4vT7wL...",
  "scope": "packs:read downloads:read"
}

Refreshing Access Tokens

Access tokens expire after 1 hour. Use the refresh token to obtain a new access token without requiring the user to re-authorize:

curl -X POST "https://auth.iconflow.dev/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=cf_9aB3dE7fGh2iJk" \
  -d "refresh_token=irt_8xK2mN9pQr4vT7wL..."

Refresh tokens are long-lived (90 days by default) but can be revoked by the user at any time from their IconFlow account settings under Connected Applications.