API Overview

Overview

The Friday API uses API key authentication. Each API key is scoped to a single company and grants access to all API endpoints allowed by that company's plan. Keys are passed via the X-API-Key header on every request.

Coming soon — OAuth 2.0 with multi-app support is on the roadmap. This will let a single application request access to multiple Friday companies through a standard authorization flow. For now, all integrations use API keys.

Before You Start

There are two common roles involved in API access:

If you are both the company admin and the developer (e.g., building an internal integration), you can enable access and generate keys yourself.

The Developer Portal supports both sandbox and production through one login. After signing in, use the environment switcher to choose where you want to manage API keys, webhooks, and request logs.

The Setup Flow

┌──────────────────────────────────────────────┐
│  1. Company admin enables API access         │  ← Inside the Friday dashboard
└──────────────────┬───────────────────────────┘
                   ▼
┌──────────────────────────────────────────────┐
│  2. Portal account is created automatically  │  ← For the company admin
└──────────────────┬───────────────────────────┘
                   ▼
┌──────────────────────────────────────────────┐
│  3. Admin signs in to the Developer Portal   │  ← Same login for sandbox + production
└──────────────────┬───────────────────────────┘
                   ▼
┌──────────────────────────────────────────────┐
│  4. Admin generates an API key               │  ← In the portal's API Keys page
└──────────────────┬───────────────────────────┘
                   ▼
┌──────────────────────────────────────────────┐
│  5. Optional: invite additional developers   │  ← Third parties or teammates
└──────────────────┬───────────────────────────┘
                   ▼
┌──────────────────────────────────────────────┐
│  6. Invited developers accept invitations    │  ← In the portal's Notifications page
└──────────────────┬───────────────────────────┘
                   ▼
┌──────────────────────────────────────────────┐
│  7. Make your first API call                 │  ← X-API-Key header
└──────────────────────────────────────────────┘

Step 1 — Company Admin Enables API Access

A Friday company admin enables API access from the Friday dashboard:

1. Navigate to Settings → API / Developer Access.
2. Enable API access for the company.

Once enabled, Friday automatically creates a Developer Portal account for that admin.

Step 2 — Sign In to the Developer Portal

The company admin can now sign in to the Developer Portal. The same portal login works for both sandbox and production; use the environment switcher to choose which environment you are managing.

Step 3 — Generate an API Key

Navigate to the API Keys page in the Developer Portal.

1. Click Generate Key.
2. Select the company from the dropdown.
3. Optionally add a label to help you identify the key later (e.g., "Production", "Staging", "Internal sync").
4. Click Generate.

The portal displays your full API key once. It looks like this:

fri_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Copy it now and store it securely. The full key is never shown again. If you lose it, you'll need to revoke it and generate a new one.

After creation, the API Keys page shows only the key prefix (the first 12 characters) for identification purposes, along with the label, company, creation date, and last-used timestamp.

Key format

All API keys start with the fri_ prefix followed by 64 hexadecimal characters, totaling 68 characters.

Revoking a key

You can revoke a key at any time from the API Keys page. Revoked keys stop working immediately and cannot be reactivated. Generate a new key if you need to replace one.

Step 4 — Optional: Invite Additional Developers

Company admins can invite additional third-party developers or teammates who need to help build the integration. Invited developers sign in to the Developer Portal, verify their email if prompted, then accept the company invitation from Notifications.

Once an invitation is accepted, that developer can generate API keys for the company in the selected environment.

Step 5 — Choose Sandbox or Production

The Developer Portal has a single login for both environments:

API keys are environment-specific. A sandbox key only works with the sandbox base URL, and a production key only works with the production base URL.

For initial testing, use sandbox.

Step 6 — Make Your First API Call

With your API key, you can call any API endpoint. Pass the key in the X-API-Key header:

curl -X GET https://node.friday-staging.com/partner/v1/companies \
  -H "X-API-Key: fri_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"

A successful response looks like:

{
  "company_id": 42,
  "name": "Acme Corp",
  "address": {
    "street_1": "123 Main St",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "90001"
  },
  "phone": "555-123-4567",
  "plan_name": "payroll",
  "created_at": "2025-06-15T08:30:00.000Z"
}

If something is wrong with the key, you'll get a 401:

{
  "error": "Invalid API key"
}

Authentication Details

How it works

Every request to /partner/v1/* must include the X-API-Key header. The API validates the key, resolves which company it belongs to, and scopes all data access to that company.

One key, one company

Each API key is tied to a single company. If you integrate with multiple Friday companies, you'll need a separate key for each (one accepted invitation per company, one or more keys per invitation).

No scopes

API keys grant access to all API endpoints. Access is gated by the company's plan, not by per-key permissions:

If you call an endpoint that requires a higher plan, the API returns 403:

{
  "error": "Your plan does not include access to this resource. Please upgrade to the payroll plan."
}

Rate Limiting

The Friday API enforces a rate limit of 100 requests per 60 seconds per API key (sliding window).

When you exceed the limit, the API returns 429 Too Many Requests. Back off and retry after the window resets.

Viewing Request Logs

The Developer Portal includes a request log viewer for each API key. Navigate to API Keys → (select a key) to see a filterable log of every request made with that key, including:

• Timestamp
• HTTP method and path
• Response status code

You can filter by method, path, status code, and date range. This is useful for debugging integration issues.

Common Pitfalls

• Unverified email — Invited developers cannot log in until they verify their email. Check spam if the verification email doesn't arrive.
• Lost API key — The full key is only shown once at generation time. If you lose it, revoke the old key and generate a new one.
• Wrong environment — Sandbox and production keys are separate. Make sure the key matches the base URL you are calling.
• Wrong plan — Some endpoints require a payroll or premium plan. If you get a 403 referencing your plan, check with the company admin about their current plan level.
• Rate limit exceeded — If you receive 429 responses, throttle your requests to stay under 100 per 60 seconds per key.

Quick Reference

What's Next

• Explore the API — Visit the API Reference for the full endpoint reference, including request/response schemas and query parameters.
• Process payroll — If the company is on a payroll plan, see the Payroll Processing guide for a step-by-step walkthrough.
• Set up webhooks — Stay in sync with Friday by subscribing to real-time events. See the Webhooks section in the Developer Portal dashboard.
• OAuth (coming soon) — Multi-app OAuth 2.0 support is on the roadmap. This will allow a single application to request authorized access to multiple Friday companies without managing individual API keys. Stay tuned for updates in the Developer Portal.