Native sign-in

Use this flow when your client signs users in with their own email address — a mobile or desktop app, for example. For scripts and integrations acting with a token you generated yourself, use a personal access token instead.

	Personal access token	Session token
Who it represents	You, the token holder	The signed-in user
How it is obtained	Generated at /me/access_tokens	This flow
Lifetime	Until revoked	14 days of inactivity, sliding
Sent as	Authorization: Bearer …	Cookie: session_token=…
User revokes at	/me/access_tokens	/me/sessions

Operations

Method	Path	Purpose
POST	/session	Email a 6-character sign-in code
POST	/session/magic_link	Exchange the code for a session token
POST	/session/two_factor	Complete 2FA, if the account requires it
DELETE	/session	Sign out, destroying the session

1. Request a code

curl -X POST https://app.paidcollabs.com/session \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"email_address": "[email protected]"}'

{ "pending_authentication_token": "eyJfcmFpbHMi..." }

Returns 201 Created. The user receives a 6-character code by email, valid for 15 minutes.

Always 201

This endpoint returns the same response whether or not the address belongs to an existing account — a new account is created on first sign-in, and unknown or malformed addresses are indistinguishable. You cannot use it to check whether someone has an account.

Store the pending_authentication_token and send it back in step 2. It is also set as a cookie, so a client with a cookie jar can ignore the response body entirely.

2. Exchange the code

curl -X POST https://app.paidcollabs.com/session/magic_link \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Pending-Authentication-Token: eyJfcmFpbHMi..." \
  -d '{"code": "ABC123"}'

{ "session_token": "eyJfcmFpbHMi..." }

Store the session_token somewhere durable and private — the Keychain on Apple platforms, the Keystore on Android.

Failures are deliberately uniform

A wrong code, an expired code, and a code issued to a different address all return an identical 401 Unauthorized with a generic message. Do not branch on the reason; there isn’t one to read.

If the account has two-factor authentication

Step 2 returns 202 Accepted instead:

{ "two_factor_required": true, "pending_two_factor_token": "eyJfcmFpbHMi..." }

Prompt for the TOTP code (or a backup code) and post it within 5 minutes:

curl -X POST https://app.paidcollabs.com/session/two_factor \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -H "X-Pending-Two-Factor-Token: eyJfcmFpbHMi..." \
  -d '{"two_factor": {"code": "123456"}}'

The response is the same { "session_token": … } as above.

3. Authenticate requests

Send the session token as a cookie:

curl -H "Cookie: session_token=eyJfcmFpbHMi..." \
     -H "Accept: application/json" \
     https://app.paidcollabs.com/organizations.json

A cookie rather than a Bearer header, deliberately — it is the same credential the web app uses, so there is a single session mechanism on both sides. Most HTTP clients will do this for you automatically if you keep their cookie jar between requests.

Every request slides the 14-day inactivity window. The user can revoke any session from /me/sessions, and revocation takes effect on the next request.

4. Sign out

curl -X DELETE https://app.paidcollabs.com/session \
  -H "Accept: application/json" \
  -H "Cookie: session_token=eyJfcmFpbHMi..."

Returns 204 No Content and destroys the session server-side. Discard your stored copy.

Not supported

• OAuth / OpenID Connect. There is no authorization-code flow and no client registration. If you need a third-party integration where your users grant your app access to their PaidCollabs data, that does not exist yet — get in touch.
• Password sign-in. PaidCollabs has no passwords.
• Social sign-in. Google and Apple sign-in are web-only; there is no JSON equivalent.