🔐 Authentication & Rate Limits

To work with the FlexPay API, you’ll need to authenticate every request using a secure, token-based method. FlexPay uses Bearer tokens tied to your organization’s credentials. These tokens are created and managed within the Developer → API Keys section of the FlexPay Admin Dashboard. Each token is associated with specific scopes — such as read:employees or write:payroll — which control what the token can access or modify. You must include this token in the Authorization header of every API request. Tokens offer fine-grained access control, meaning they can be tailored to limit the surface area of exposure when integrating with payroll automations, employee management tools, or time-tracking systems.

All FlexPay API endpoints require secure HTTPS connections. Any requests made over insecure channels (HTTP) will be automatically rejected to ensure data integrity and protect sensitive employee data such as compensation, pay groups, and banking details. Before making your first request, it’s important to understand how both authentication and rate limiting work — especially if your app will perform high-volume batch operations like onboarding hundreds of employees or submitting weekly payroll in real time.

---

🌐 Base URL

arduinoCopyEdithttps://api.flexpay.dev/v1/

---

🧭 Getting Your Token

To create a token:

1. Log in to your FlexPay Admin Dashboard

2. Navigate to Developer → API Keys

3. Click Generate Token

4. Choose a scope: Read-only, Payroll Submitter, or Admin

5. Copy and store the token securely — tokens are only shown once

---

Figure 1. Generate a New Token by Navigating from Developer -> API Keys in FlexPay Admin Dashboard

---

🔐 Example Authenticated Request

bashCopyEditcurl -X GET https://api.flexpay.dev/v1/paystubs \
  -H "Authorization: Bearer sk_live_abc123..."

---

🎯 Token Scopes

Each token can have one or more of the following scopes:

• read:employees — View employee data

• write:payroll — Submit or modify payroll runs

• read:paystubs — Retrieve paystub data

Use minimum scope tokens whenever possible. This protects you in case tokens are compromised and allows easier debugging when permission errors occur.

---

🚦 Rate Limits

FlexPay applies tiered rate limiting to maintain service reliability. Each token has limits based on:

• Burst capacity (how many requests you can send quickly)

• Sustained rate (how many requests you can send over time)

• Endpoint type and scope

If a limit is exceeded, you’ll receive a structured error response like:

jsonCopyEdit{
  "error": "Rate limit exceeded",
  "retry_after": 60
}

Headers to watch:

• X-RateLimit-Limit

• X-RateLimit-Remaining

• X-RateLimit-Reset

---

Figure 2. FlexPay's Burst/Sustain Model to Protect Traffic and API Uptime

---

🔐 Security Best Practices

• Never commit your token to GitHub or public repositories

• Store tokens in secure environment variables or vaults

• Rotate tokens every 30–60 days

• Use scoped tokens for every external integration

• Audit access with the Developer → Logs section

---

🧾 Summary

Authentication is the secure backbone of the FlexPay API experience. It starts with creating your own Bearer token inside the Developer → API Keys section. This token defines what your app can do, how fast it can operate, and how long it can stay active. Tokens that include green-labeled scopes like read:paystubs or write:payroll act as passports to sensitive employee and payroll data. If a token is malformed, expired, or missing required scopes, requests will fail with clear error messages to help you debug quickly.

By default, most tokens have rate caps to prevent misuse — typically 300 requests/minute for reads, and 100 writes/minute for payroll. Enterprise partners can request upgrades. FlexPay uses burst and sustain windows to smooth out traffic spikes while maintaining consistent performance for everyone. Understanding your limits upfront helps you design systems that retry or throttle gracefully.

We recommend using Postman or similar tools to test your first authenticated request, then gradually build automation flows. Every call you make must include the Authorization: Bearer header, or it will be rejected. If you see 401 Unauthorized or 403 Forbidden, your token is likely missing required scopes.

---

⏭️ What’s Next?

Now that you know how authentication and rate limiting work in FlexPay, you're ready to make your first authenticated call: onboarding a new employee. In the next section — ➕ Add Employee (POST /employees) — you'll see how authentication combines with properly scoped tokens and previously configured green pay groups and employment types to create new employee records programmatically.

We’ll walk through:

• Crafting the request body using the correct data schema

• How your pay schedule affects the new employee setup

• What to expect in the response — including employee_id

• Error handling when a required field is missing

• Testing the flow in Postman or curl

• How onboarding employees via API ties into payroll submission

This is the moment when your token becomes a tool, not just a string. Let’s move to the next section and start building real automation flows with FlexPay.