Skip to main content

Authentication

All Affilync API requests require authentication. You can use either JWT tokens (for user sessions) or API keys (for server-to-server integrations).

Base URL​

https://api.affilync.com/api

All endpoints are prefixed with /api/.

Option 1: API Key Authentication​

Include your API key in the X-API-Key header:

curl https://api.affilync.com/api/campaigns \
  -H "X-API-Key: afk_live_abc123xyz..."

API keys are only accepted via the X-API-Key header. Sending an API key as Authorization: Bearer … will fail — that header is reserved for JWT access tokens.

API keys are created in Settings > Security > API Keys. See Security for key management details.

Option 2: JWT Authentication​

Login​

curl -X POST https://api.affilync.com/api/auth/login/affiliate \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

Or for brands:

curl -X POST https://api.affilync.com/api/auth/login/brand \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

Response (200):

{
  "success": true,
  "message": "Login successful",
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 900,
  "user": {
    "id": "uuid",
    "email": "[email protected]",
    "user_type": "affiliate",
    "subscription_tier": "free"
  }
}

Use the Access Token​

Include the access token in subsequent requests:

curl https://api.affilync.com/api/campaigns \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Refresh the Token​

Access tokens expire after 15 minutes. Use the refresh token to get a new pair:

curl -X POST https://api.affilync.com/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "eyJhbGciOiJSUzI1NiIs..."
  }'

Response (200):

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 900
}

Refresh tokens expire after 3 days or when a new refresh token is issued. Sessions are invalidated on each login to prevent session fixation attacks.

Two-Factor Authentication (2FA)​

Enable TOTP-based two-factor authentication for enhanced account security. When 2FA is enabled on login, the API returns an MFA challenge token instead of full credentials.

Setup 2FA​

curl -X POST https://api.affilync.com/api/2fa/setup \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200):

{
  "success": true,
  "qr_code": "data:image/png;base64,...",
  "secret": "JBSWY3DPEBLW64TMMQ======",
  "backup_codes": [
    "a1b2c3d4",
    "e5f6g7h8",
    ...
  ],
  "message": "Scan the QR code with your authenticator app"
}

Enable 2FA​

curl -X POST https://api.affilync.com/api/2fa/enable \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "totp_code": "123456"
  }'

Verify 2FA on Login​

When 2FA is enabled, login returns an MFA challenge token. Verify the TOTP code:

curl -X POST https://api.affilync.com/api/2fa/verify \
  -H "Content-Type: application/json" \
  -d '{
    "mfa_challenge_token": "eyJhbGciOiJSUzI1NiIs...",
    "totp_code": "123456"
  }'

Get 2FA Status​

curl -X GET https://api.affilync.com/api/2fa/status \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200):

{
  "enabled": true,
  "backup_codes_remaining": 7,
  "setup_completed_at": "2024-01-15T10:30:00Z"
}

Disable 2FA​

curl -X POST https://api.affilync.com/api/2fa/disable \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "password": "your-password"
  }'

Token Details​

PropertyValue
Access token lifetime15 minutes
Refresh token lifetime3 days
Token formatJWT (JSON Web Token)
Authorization headerAuthorization: Bearer <access_token>

Error Responses​

StatusMeaning
401 UnauthorizedMissing, expired, or invalid token
403 ForbiddenValid token but insufficient permissions/scopes; or MFA required
423 LockedToo many failed login attempts; account temporarily locked
{
  "detail": "Token has expired",
  "error_code": "TOKEN_EXPIRED"
}

MFA-required response:

{
  "success": false,
  "mfa_required": true,
  "mfa_challenge_token": "eyJhbGciOiJSUzI1NiIs...",
  "message": "Two-factor authentication required. Please verify with your authenticator app."
}

Best Practices​

  • Use API keys for backend integrations and JWT tokens for user-facing applications.
  • Store tokens securely -- never expose them in client-side code or URLs.
  • Always use httpOnly cookies for web clients; mobile clients may receive tokens in the response body.
  • Implement automatic token refresh before the 15-minute expiry to avoid interruptions.
  • Restrict each API key with an IP allowlist so it can only be used from your own servers.
  • Enable 2FA on all production accounts for enhanced security.
  • Rotate API keys regularly (recommended: every 90 days).

Next Steps​