> For the complete documentation index, see [llms.txt](https://docs.joinflo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.joinflo.com/authentication.md).

# Authentication

## Authentication

Flo's APIs accept two ways to authenticate:

* **An API key** (recommended). A key belongs to your organization, not to a person, and is sent with every request. There is no password, MFA secret or sign-in call to manage.
* **An administrator session** (legacy). Your integration signs in as a dedicated Flo administrator account and sends the session cookie it receives. This still works; see Session login (legacy).

### API keys

A request made with an API key acts as your organization. It can read and change only your organization's data, and any change is recorded as made by your integration rather than by a member of your team.

#### Get a key

Ask your Flo Customer Success Manager for an API key. Tell them:

* which administrator in your organization owns the integration, and
* what the integration will do.

Flo issues the key and gives it to that administrator. The full key is shown only once. Flo stores only a hash of it and cannot show it to you again, so store it as soon as you receive it. If you lose it, ask for a new one.

The integration does not appear in your Members list and cannot sign in to Flo.

#### Use the key

Send the key in the `Authorization` header with the `Bearer` scheme, on every request, over HTTPS:

```bash
curl https://api.florecruit.com/v1/users \
  -H "Authorization: Bearer $FLO_API_KEY"
```

* **Format:** production keys start with `flo_prod_`, followed by 64 hexadecimal characters.
* **Header only.** A key in a URL or query string is not accepted.
* **One identity per request.** If a request carries both a key and a session cookie, the cookie is ignored and the request acts as your organization.

> **The Public Jobs API doesn't use a key.** It needs no authentication at all, so leave the `Authorization` header off those requests: a request to it that carries a key is refused.

#### When a request is refused

| Status                    | What it means                                                                                                                                                                                |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`        | The key is missing, unknown, revoked, expired, or was issued for a different Flo environment. Check that you are sending the whole key; if it was revoked or has expired, ask for a new one. |
| `403 Forbidden`           | The key is valid, but it can't be used for this request.                                                                                                                                     |
| `503 Service Unavailable` | A temporary problem on Flo's side. Retry with backoff. Your key is still valid, so don't replace it.                                                                                         |

On the HRIS API, `401` can also mean the HRIS API isn't enabled for your organization. If a new key gets `401` there, contact Flo before replacing it.

#### Expiry and rotation

A key expires 12 months after it is issued, or earlier if you ask for a shorter lifetime. Flo tells you the expiry date when it issues the key. Note it, so you can rotate before it lapses.

Your organization can hold more than one active key, so you can rotate without downtime:

1. Ask Flo for a second key.
2. Deploy it to your integration and confirm requests succeed.
3. Ask Flo to revoke the old key.

When you contact Flo about a key, identify it by its first characters, for example `flo_prod_1a2b3c4d`. Never send the whole key by email or chat.

#### Keep the key secret

* Store the key in a secrets manager or an environment variable. Never commit it to source control or ship it in browser or mobile code.
* Call the API over HTTPS only. Treat a key that was ever sent over plain HTTP as exposed.
* Give each integration its own key, so you can revoke one without stopping the others.

If a key is exposed, contact Flo Support and ask for it to be revoked. A revoked key stops working within a minute.

### Session login (legacy)

Before API keys, integrations signed in as a dedicated Flo administrator account and sent the resulting session cookie with each request. This still works, but we recommend moving to an API key: there is no password or MFA secret to store, no sign-in call before each request, and no administrator account tied up by the integration.

#### How to Create an Admin Service Account for Public API Access

This guide explains how to create a new Admin account in Flo specifically for programmatic API access (a "service account"). This account is used by software systems or scripts to authenticate with the Flo API.

You must be a current Flo Admin to perform these steps.

**Part 1: Prerequisites**

Before you begin, you must have a dedicated email address ready for this new service account (e.g., <api.user@yourcompany.com>). You will need access to this email account's inbox to complete the setup.

**Part 2: Create New Admin Member & Determine Auth Path**

1. From your Admin account, click Members in the main navigation bar on the left side of the screen.

![](https://2238658898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqIeTbiO9bTiaTwaGTY0I%2Fuploads%2Fn7ZH4oUhWJnt1A5BntOP%2Funknown.png?alt=media\&token=1851dea8-374c-4d90-a0af-b37d45979f38)

2. On the Members list page, click the "Create New Member" button (this is typically in the top right corner).
3. A new window/modal will appear. Fill in the information for the new service account member:
   1. Admin Status: Select “Admin” for Admin Status
   2. Login type: If your organization has MFA enabled, select MFA
      1. Note: If your organization does not have MFA or SSO enabled you will not see these options and will log in using email and password.
   3. First Name: Recommend using “API”
   4. Last Name: Recommend using “User”
   5. Email: The dedicated email address you prepared.\
      ![](https://2238658898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqIeTbiO9bTiaTwaGTY0I%2Fuploads%2Fk5aF1KVbaWSBqP8L5EdU%2Funknown.png?alt=media\&token=b92334f6-e8a2-4fb6-a36c-70b4d7d3b733)
4. Determine Your Authentication Path:
   1. When you check "Admin," a new radio group called “Login type” may appear asking if this user requires extra security (SSO or MFA) to log in.
   2. If you see this option OR you know your org requires MFA for admins: You are an MFA-Enabled Org. You must select the MFA option (if presented). After clicking "Send Invite," you will follow Part 3, Path B.
   3. If you do NOT see this option AND you know your org does not use MFA: You are a Non-MFA Org. After clicking "Create Member," you will follow Part 3, Path A.
   4. If you are unsure: Please contact your Customer Success representative to confirm your org's admin authentication settings before proceeding.
5. Click “Create Member” and an email will be sent to finish the new account creation (setup from email still needed in following steps).

**Part 3: Finalize Account Setup**

Follow the instructions that match the path you determined in Part 2.

**Path A: For non-MFA Orgs**

1. Go to the inbox for the new service account's email address.
2. Open the invitation email, subject: “New Flo Account for You” from Flo and click the activation link, “Click here to create your account”.
3. A web page will open in your default browser, prompting you to create a password.
4. Create a strong, unique password for this account.
   1. Flo recommends using a password manager (like 1Password or LastPass) to generate and store a password.
   2. If creating one manually, ensure it is long (16+ characters) and complex (using uppercase, lowercase, numbers, and symbols).
   3. Store this password securely. You will need it for your API configuration.
5. Your setup is complete. This account is now active. Proceed to Part 4: Securely Store Credentials.

<br>

**Path B: For MFA-Enabled Orgs**

This path requires extra steps to retrieve the MFA secret key for programmatic use.

1. Follow Path A steps 1-4 to set up a new password for this account.
2. After setting the password, you will be logged in. Log out and navigate to your organization’s login page. If your organization has SSO enabled, you will need to enter this URL in the browser to access the normal login form:
   1. <https://florecruit.com/app/your_organization_name/adminLoginMfaForSsoOrg/>
3. Click the "Forgot password?" link.\
   ![](https://2238658898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqIeTbiO9bTiaTwaGTY0I%2Fuploads%2FPftF0hMzDai2Tnm55o9b%2Funknown.png?alt=media\&token=ad001472-d6a1-4e35-93d4-c141a84d410a)
4. Enter the service account's email address and submit the form.![](https://2238658898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqIeTbiO9bTiaTwaGTY0I%2Fuploads%2FDg1Z1Fd3AdxHMCFBSsD5%2Funknown.png?alt=media\&token=e073ad8a-0445-498c-8f9d-c9a424f735c7)
5. Go back to the service account's email inbox. Open the new "Forgot Password Account Recovery" email and click the link.
6. You will be prompted to create a new password again. Enter a new, secure password.
7. Once you submit this new password, the page will load the MFA Setup screen showing a QR code.
8. Below the QR code, click the link "show secret key for manual configuration".![](https://2238658898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqIeTbiO9bTiaTwaGTY0I%2Fuploads%2FPgkRZDU2jDL7ltyjWQsI%2Funknown.png?alt=media\&token=bfeabf19-06e0-43e0-a9a4-968bdbe5365b)
9. A text string will appear. Click the copy button to copy this MFA Secret Key to your clipboard. Store this secret key somewhere safe, Part 4 will go over how to use this secret key.![](https://2238658898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqIeTbiO9bTiaTwaGTY0I%2Fuploads%2F1C04viDJXff7sBlJiNBq%2Funknown.png?alt=media\&token=475859f4-0912-4457-88b1-bde3797c28b2)
10. Finish the MFA setup by scanning the QR code with an MFA application. Enter the 6 digit code in the form field “MFA Code”.
11. You should now be logged in to the system. Log out.
12. Your setup is complete. Proceed to Part 4: Securely Store Credentials.

**Part 4: Securely Store Credentials**

You must securely store these credentials for your application to use.

* Credentials from Part 3 should never be stored in an unsecure location. Do not email or share your credentials with anyone.
* Programmatic access will require storing credentials in the environment where your code will be running to access the API. It is recommended that you use a .env file or store these credentials as environment variables and load them when running your application. If going .env route we recommend it to your gitignore file and not checking it into git.
* For Non-MFA Orgs: You need the Email and Password.
* For MFA-Enabled Orgs: You need the Email, Password, and the MFA Secret Key you just copied.

**Part 5: Next Steps**

Your admin service account is now fully configured.

We suggest that you authenticate prior to each API request. That will involve you making a POST request with your credentials to our Login Endpoint.\
\
The Login Endpoint is

[https://florecruit.com/app/{org\_name}/admin/auth/](https://florecruit.com/app/%7Bcreds\['site_name']%7D/admin/auth/)

The endpoint always returns a 200 OK status response. If the Authentication was successful, it will also contain a cookie containing an authorization token.

To verify authentication succeeded, make a test API call after authenticating. If the test call returns 401 Unauthorized, authentication failed—check your credentials and ensure you've included mfaCode if your account requires MFA.

Refer to the “Python Code Example” and “[Node.js](http://node.js) Code Example” sections at the end of this document for more specifics about usage.

**Example Setup Using Postman**

The following screenshots walk you through setting up Postman to successfully authenticate with the Flo API.

Postman Example showing how to set the Auth Cookie

<figure><img src="https://2238658898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqIeTbiO9bTiaTwaGTY0I%2Fuploads%2FuwNZnCq1esof7bFnzJoB%2FScreenshot%202026-03-27%20at%2012.14.57%E2%80%AFPM.png?alt=media&#x26;token=98082ab8-8436-48ff-b24c-4dfa44140aa7" alt=""><figcaption></figcaption></figure>

Postman Example how to set the resume as part of the body of the request.

![](https://2238658898-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqIeTbiO9bTiaTwaGTY0I%2Fuploads%2FxUEhOBzFRACaIfh6f5x7%2FScreenshot%202026-03-27%20at%2012.15.06%E2%80%AFPM.png?alt=media\&token=88334251-dfd2-4325-a51c-563ceb3a2698)<br>
