Skip to content

Auth API ​

All paths are relative to https://your-site.com/api/v1. Send Authorization: Bearer <token> and Accept: application/json; see authentication and errors.

MethodPathWhat it does
POST/auth/loginSign in
POST/auth/logoutSign out (revokes the token used, or ends the dashboard session)
POST/auth/login/two-factorThe code step after "Sign in with Google" for an account with two-factor sign-in (dashboard session only; the step lasts 5 minutes)
POST/auth/email/resendSends the link that confirms the email address again (SaaS sign-ups; until confirmed, no website can be added)
POST/auth/signupCreate an account (SaaS edition, while sign-up is open)
GET/auth/invitations/{token}Check an invitation link
POST/auth/invitations/{token}/acceptCreate the account from an invitation and sign in

POST /auth/login ​

Sign in

No sign-in needed

This endpoint is public.

Request body ​

application/json, required

FieldTypeRequiredDescription
emailstring (email)yes
passwordstringyes
device_namestringRequired for token clients, e.g. "Ada's iPhone". At most 120 characters.
rememberbooleanDashboard session only.
recaptchastringWhile an administrator switched reCAPTCHA on: the page's Google reCAPTCHA v3 token for action "login" (dashboard sign-ins only; API clients don't send one). Otherwise a 422 on "recaptcha".
codestringAccounts with two-factor sign-in: the authenticator app's 6-digit code or a recovery code. Without it, after the right password, a 422 on "code" asks for it; send everything again with it. 10 wrong codes lock the account for 15 minutes. At most 20 characters.

Responses ​

  • 200 — Signed in. Token clients also get token and token_type.
  • 422 — Validation failed.
  • 429 — Rate limit hit.
Response fields
FieldTypeRequiredDescription
dataobject
data.idinteger
data.namestring
data.emailstring
data.email_verifiedbooleanWhether the address is confirmed (SaaS sign-ups confirm it by email before they can add a website).
data.localestring, nullableInterface language chosen by the person (null = the browser's)
data.timezonestring, nullableTime zone the dashboard shows dates in (IANA name such as Europe/Berlin; null = the browser's)
data.preferencesobjectThe person's own preferences that follow them to every browser (e.g. replay.cursor, replay.trail).
data.is_adminboolean
data.account_rolestringmanager: everything incl. team and billing; member: everything but team and billing; viewer: read-only. One of: manager, member, viewer.
data.site_idsinteger[], nullableSites the person is limited to; null = every site.
data.organizationobject, nullable
data.organization.idinteger
data.organization.namestring
tokenstring
token_typestring
bash
curl -X POST "https://your-site.com/api/v1/auth/login" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"text","device_name":"text","remember":true,"recaptcha":"text","code":"text"}'

POST /auth/logout ​

Sign out (revokes the token used, or ends the dashboard session)

Responses ​

  • 204 — Signed out.
  • 401 — Not signed in.
bash
curl -X POST "https://your-site.com/api/v1/auth/logout" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

POST /auth/login/two-factor ​

The code step after "Sign in with Google" for an account with two-factor sign-in (dashboard session only; the step lasts 5 minutes)

Request body ​

application/json, required

FieldTypeRequiredDescription
codestringyesAt most 20 characters.

Responses ​

  • 200 — Signed in: data is the User.
  • 422 — Wrong code, too many wrong codes, or the step expired (sign in again).
bash
curl -X POST "https://your-site.com/api/v1/auth/login/two-factor" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"code":"text"}'

POST /auth/email/resend ​

Sends the link that confirms the email address again (SaaS sign-ups; until confirmed, no website can be added)

Responses ​

  • 202 — data.sent_to
  • 401 — Not signed in.
  • 409 — The address is confirmed already.
  • 503 — The email could not be sent.
bash
curl -X POST "https://your-site.com/api/v1/auth/email/resend" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

POST /auth/signup ​

Create an account (SaaS edition, while sign-up is open)

No sign-in needed

This endpoint is public.

Request body ​

application/json, required

FieldTypeRequiredDescription
namestringyes
companystring, nullableAccount name; default "<name>'s workspace".
emailstring (email)yes
passwordstringyesAt least 8 characters.
password_confirmationstringyes
device_namestringRequired for token clients.
recaptchastringWhile reCAPTCHA is on: a Google reCAPTCHA v3 token for action "signup"; otherwise a 422 on "recaptcha".
termsbooleanyesMust be true: the terms of service (/terms) and privacy policy (/privacy) are accepted; the moment is stored.

Responses ​

  • 201 — Signed in. Token clients also get token and token_type.
  • 403 — Sign-up is closed.
  • 422 — Validation failed.
Response fields
FieldTypeRequiredDescription
dataobject
data.idinteger
data.namestring
data.emailstring
data.email_verifiedbooleanWhether the address is confirmed (SaaS sign-ups confirm it by email before they can add a website).
data.localestring, nullableInterface language chosen by the person (null = the browser's)
data.timezonestring, nullableTime zone the dashboard shows dates in (IANA name such as Europe/Berlin; null = the browser's)
data.preferencesobjectThe person's own preferences that follow them to every browser (e.g. replay.cursor, replay.trail).
data.is_adminboolean
data.account_rolestringmanager: everything incl. team and billing; member: everything but team and billing; viewer: read-only. One of: manager, member, viewer.
data.site_idsinteger[], nullableSites the person is limited to; null = every site.
data.organizationobject, nullable
data.organization.idinteger
data.organization.namestring
tokenstring
token_typestring
bash
curl -X POST "https://your-site.com/api/v1/auth/signup" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"text","company":"text","email":"[email protected]","password":"text","password_confirmation":"text","device_name":"text","recaptcha":"text","terms":true}'

GET /auth/invitations/{token} ​

Check an invitation link

No sign-in needed

This endpoint is public.

Parameters ​

NameInTypeRequiredDescription
tokenpathstringyesThe secret from the invitation link. Pattern ^[A-Za-z0-9]{48}$.

Responses ​

  • 200 — The invited address, and the account they join (null = a new account).
  • 404 — Unknown, used or expired link.
Response fields
FieldTypeRequiredDescription
dataobject
data.emailstring
data.organizationstring, nullable
bash
curl -X GET "https://your-site.com/api/v1/auth/invitations/{token}" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json"

POST /auth/invitations/{token}/accept ​

Create the account from an invitation and sign in

No sign-in needed

This endpoint is public.

Parameters ​

NameInTypeRequiredDescription
tokenpathstringyesThe secret from the invitation link. Pattern ^[A-Za-z0-9]{48}$.

Request body ​

application/json, required

FieldTypeRequiredDescription
namestringyes
passwordstringyesAt least 8 characters.
password_confirmationstringyes
device_namestringRequired for token clients.

Responses ​

  • 201 — Signed in. Token clients also get token and token_type.
  • 422 — Validation failed.
Response fields
FieldTypeRequiredDescription
dataobject
data.idinteger
data.namestring
data.emailstring
data.email_verifiedbooleanWhether the address is confirmed (SaaS sign-ups confirm it by email before they can add a website).
data.localestring, nullableInterface language chosen by the person (null = the browser's)
data.timezonestring, nullableTime zone the dashboard shows dates in (IANA name such as Europe/Berlin; null = the browser's)
data.preferencesobjectThe person's own preferences that follow them to every browser (e.g. replay.cursor, replay.trail).
data.is_adminboolean
data.account_rolestringmanager: everything incl. team and billing; member: everything but team and billing; viewer: read-only. One of: manager, member, viewer.
data.site_idsinteger[], nullableSites the person is limited to; null = every site.
data.organizationobject, nullable
data.organization.idinteger
data.organization.namestring
tokenstring
token_typestring
bash
curl -X POST "https://your-site.com/api/v1/auth/invitations/{token}/accept" \
  -H "Authorization: Bearer $REPLORA_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"text","password":"text","password_confirmation":"text","device_name":"text"}'

Replora: see what your visitors see.