Authentication

The PurpletGo API supports two authentication methods: API keys (for server-to-server integrations - this is what the rest of this reference assumes) and session cookies (used by the web app itself).

API keys

Generating an API key

Go to Settings → API Keys
Click Generate New Key
Give the key a name and select its scopes
Copy the key immediately - it is only shown once, in the response of the create call

⚠️

The full key value is only ever returned at creation time. PurpletGo doesn't store it in plaintext and can't show it to you again - only a short prefix is kept for identification. If you lose it, revoke the key and generate a new one.

Authenticating requests

Include the API key in the Authorization header as a Bearer token:

Authorization: Bearer fnl_live_••••••••••••••••••••••••••••••••

Example:

curl https://app.purpletgo.com/api/v1/employees \
  -H "Authorization: Bearer fnl_live_••••••••••••••••••••••••••••••••"

Key format

Keys are generated as fnl_ followed by an environment segment and 32 hex characters:

Prefix	Environment
`fnl_live_`	Production
`fnl_test_`	Test / staging

Requests with a malformed key, or a key that doesn't match a stored hash, get back 401 Unauthorized with a generic Invalid or unauthorized API key message - PurpletGo deliberately doesn't distinguish "key not found" from "key revoked" from "key expired" in the error text, to avoid leaking which keys exist.

Scopes

Each API key is created with one or more scopes that limit what it can do:

Scope	Description
`offboardings:read`	List and view offboardings
`offboardings:write`	Create offboardings and update their status
`employees:read`	List employees
`webhooks:read`	List registered webhooks
`webhooks:write`	Create and delete webhooks

A request to an endpoint whose scope isn't on the key gets a 403 Forbidden naming the missing scope.

Revoking keys

To revoke a key: Settings → API Keys → click Revoke next to the key.

Revoked keys are immediately invalid. Any in-flight requests using a revoked key will receive 401 Unauthorized. Revocation can't be undone - you'll need to generate a new key.

Session cookies (web app)

The PurpletGo web app authenticates with a JWT stored in an HttpOnly access_token cookie, set when you log in. This is managed automatically by the app - you don't need to handle it manually, and it isn't the recommended way to integrate with PurpletGo from your own systems (use an API key instead).

If you're building a browser-based tool and need to authenticate the same way the web app does, you can log in via POST /api/auth/login below and the cookie will be set on the response. The same endpoints will also accept the token as a Bearer header if you'd rather manage it yourself.

Auth endpoints

Login

POST /api/auth/login

Authenticate with email and password. On success, sets the access_token session cookie and returns the user in the response body - there's no token in the JSON response, it only ever travels in the cookie.

Request body

{
  "email": "admin@acme.com",
  "password": "••••••••"
}

Response 200 OK

{
  "user": {
    "id": "usr_abc123",
    "email": "admin@acme.com",
    "fullName": "Jane Smith",
    "orgId": "org_xyz",
    "role": "admin"
  }
}

If the account has two-factor authentication enabled, login instead returns a short-lived challenge and no cookie is set yet:

{ "require2fa": true, "challengeToken": "eyJ..." }

If the organisation enforces SSO, login is rejected with 403 and a redirect URL to the identity provider instead of a normal error.

Limited to 10 attempts per 15 minutes per IP.

Register

POST /api/auth/register

Create a new account and organisation. Self-service registration only works for the very first organisation on a PurpletGo instance - once one exists, new users must be invited from Settings → Team.

Request body

{
  "fullName": "Jane Smith",
  "email": "jane@acme.com",
  "password": "min8chars",
  "orgName": "Acme Corp",
  "acceptPrivacy": true
}

Response 202 Accepted

Registration doesn't create the account immediately - it sends a verification email and the account is created only once the link is clicked.

{
  "pending": true,
  "message": "Check your email to verify your address and activate your account."
}

Limited to 5 registrations per hour per IP.

Logout

POST /api/auth/logout

Revokes the current session and clears the auth cookie.

Response 200 OK

{ "success": true, "ssoLogoutUrl": null }

ssoLogoutUrl is only populated when the session was established via SAML SSO and the identity provider supports Single Logout - otherwise it's null.

Get current user

GET /api/auth/me

Returns the currently authenticated user.

Response 200 OK

{
  "id": "usr_abc123",
  "email": "admin@acme.com",
  "fullName": "Jane Smith",
  "orgId": "org_xyz",
  "role": "admin",
  "theme": "system",
  "language": "en",
  "isPlatformAdmin": false
}

Overview Errors & Rate Limiting