Getting Started

Authentication

Every request to the Outfame API must be authenticated. We support two authentication methods: API keys for server-to-server integrations and OAuth 2.0 for third-party applications acting on behalf of users.

API Key Authentication

API keys are the simplest way to authenticate. Include your key in the Authorization header of every request using the Bearer scheme.

curl https://api.outfame.com/v1/accounts \
  -H "Authorization: Bearer sk_live_abc123def456ghi789"

Key types

Security — Never expose API keys in client-side code, public repositories, or browser network requests. Store them in environment variables or a secrets manager.

Creating and managing keys

1. Go to Settings → API Keys in the dashboard.
2. Click Create new key.
3. Name it and pick which scopes it should have.
4. Copy the key immediately — it's only shown once.

You can revoke a key at any time from the dashboard. Revoked keys return 401 Unauthorized immediately.

OAuth 2.0

Use OAuth 2.0 when your app needs to act on behalf of an Outfame user — typical for SaaS platforms, agencies, and multi-tenant setups.

Authorization Code Flow

1. Redirect the user

GET https://auth.outfame.com/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=accounts:read accounts:write analytics:read&
  state=random_csrf_token

2. Exchange the authorization code

POST https://auth.outfame.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTH_CODE_FROM_CALLBACK&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
redirect_uri=https://yourapp.com/callback

3. Token response

{
  "access_token": "oa_live_xYz789AbC...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "ort_xYz789AbC...",
  "scope": "accounts:read accounts:write analytics:read"
}

4. Refresh the access token

POST https://auth.outfame.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=ort_xYz789AbC...&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

Access tokens expire after 1 hour. Refresh tokens are valid for 30 days and rotate on each use.

Scopes

Scopes let you request only the permissions your application needs. Both API keys and OAuth tokens can be assigned granular scopes.

Request the minimum scopes your integration requires. Users see the full list of requested permissions during the OAuth consent screen.

Rate limits by key tier

Rate limits are enforced per API key and vary based on your plan.

See the Rate Limits guide for headers, retry strategies, and best practices.

Error responses

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key. Check that your key is correct and has not been revoked.",
    "doc_url": "https://docs.outfame.com/authentication"
  }
}

SDK authentication

Node.js

import Outfame from "@outfame/sdk";

// API key auth
const outfame = new Outfame({
  apiKey: process.env.OUTFAME_API_KEY,
});

// OAuth token auth
const outfame = new Outfame({
  accessToken: "oa_live_xYz789AbC...",
});

Python

import outfame

# API key auth
client = outfame.Client(api_key="sk_live_abc123")

# OAuth token auth
client = outfame.Client(access_token="oa_live_xYz789AbC...")

Security best practices

• Rotate API keys every 90 days.
• Use separate keys for development, staging, and production.
• Assign the minimum required scopes to each key or OAuth application.
• Monitor key usage in the dashboard — anomalies may indicate a compromised key.
• Immediately revoke any key you suspect has been exposed.