Adlyfy

Adlyfy provides a unified API for connecting advertising platforms and operating on marketing resources through one integration surface. Instead of building and maintaining separate flows for each provider, integrators use Adlyfy to authenticate tenants, connect external users to platforms, and call platform endpoints in a consistent way.

Adlyfy is built for products and teams that need reliable platform connectivity without exposing provider-specific auth complexity to their own customers.

What Adlyfy Helps You Do

connect external users to supported marketing platforms

manage platform authorization through a consistent connection flow

use one API pattern across platform operations

keep tenant access isolated by API key

trace requests through optional request metadata in the dashboard

Who This Is For

SaaS platforms embedding marketing features into their product

agencies and operators managing integrations for multiple customers

internal engineering teams building automation around advertising platforms

partners that need a secure way to connect user-owned ad accounts and call platform APIs

Core Concepts

tenant: your organization in Adlyfy

API key: the tenant credential used on every API request

external user: the user identity you act on behalf of in your own system

connection: the authorization between an external user and a platform

adAccountId: the target advertising account used by many platform endpoints

Getting Started

1. Get Your API Key from the Adlyfy Portal

Before making API calls, get your tenant API key from the Adlyfy portal.

From the portal you can:

view the current API key

regenerate the API key when needed

Use this key in the x-api-key header on all authenticated requests.

2. Create an External User Access Token

Create an access token for the external user you want to act on behalf of.

POST /auth/token

Request:

{
  "externalUserId": "external-user-123"
}

Example:

Response:

{
  "accessToken": "{{accessToken}}",
  "refreshToken": "{{refreshToken}}"
}

Use the returned access token in the Authorization header:

3. Generate a Platform Connection URL

Create a connection URL for the platform the external user wants to authorize.

POST /connections

Request:

{
  "platform": "meta",
  "redirect": "https://your-app.example.com/integrations/meta/result"
}

Example:

Response:

{
  "authUrl": "https://www.facebook.com/..."
}

4. Redirect the User to Complete Authorization

Redirect the user to the returned authUrl.

After the authorization step is completed, the user is redirected back to the redirect URL you provided.

Typical outcomes:

success: {{redirect}}?connection=success

failure: {{redirect}}?connection=failed&reason=...

5. Confirm the Connection

Before calling platform endpoints, you can verify that the connection is active.

Useful endpoints:

GET /connections

GET /connections/status

Example:

6. Start Calling Platform Endpoints

Once the connection is active, call platform endpoints with:

x-api-key

Authorization: Bearer {{accessToken}}

adAccountId when required

Example: list Meta campaigns

Example: read Meta insights

Required Headers

Most authenticated external-user requests use:

Some platform endpoints also require:

or an adAccountId query/body field, depending on the endpoint.

Optional Metadata Header

You may send an optional metadata header with a JSON value:

This header is:

stored for logs and traceability

available through the Adlyfy dashboard

useful for correlating your internal jobs or customer actions with Adlyfy activity

This header is not used for:

authentication

authorization

changing endpoint behavior

Integration Sequence

Get tenant API key from the Adlyfy portal
-> call POST /auth/token
-> receive accessToken and refreshToken

call POST /connections
-> receive authUrl

redirect the external user to authUrl
-> user completes platform authorization
-> user returns to your redirect URL

call GET /connections or GET /connections/status
-> confirm the connection is active

call platform endpoints such as /meta/*
-> include x-api-key, bearer token, and adAccountId where required

Common Mistakes

missing x-api-key

missing bearer token

creating the token for one externalUserId and creating the connection for another

calling platform endpoints before authorization is complete

omitting adAccountId on account-scoped endpoints

expecting metadata to affect request behavior instead of being saved for logs only

Adlyfy

Adlyfy#

What Adlyfy Helps You Do#

Who This Is For#

Core Concepts#

Getting Started#

1. Get Your API Key from the Adlyfy Portal#

2. Create an External User Access Token#

3. Generate a Platform Connection URL#

4. Redirect the User to Complete Authorization#

5. Confirm the Connection#

6. Start Calling Platform Endpoints#

Required Headers#

Optional Metadata Header#

Integration Sequence#

Common Mistakes#

Adlyfy

What Adlyfy Helps You Do

Who This Is For

Core Concepts

Getting Started

1. Get Your API Key from the Adlyfy Portal

2. Create an External User Access Token

3. Generate a Platform Connection URL

4. Redirect the User to Complete Authorization

5. Confirm the Connection

6. Start Calling Platform Endpoints

Required Headers

Optional Metadata Header

Integration Sequence

Common Mistakes