Auth API

Base URL

https://api.replr.ai/v1

POST/v1/auth/register

Create a new REPLR account. A verification email is sent automatically.

Request Body

Name	Type	Required	Description
`email`	string	Required	User email address.
`password`	string	Required	Password (min 8 characters, must include a number and uppercase letter).
`username`	string	Required	Unique username (3-32 characters, alphanumeric and underscores).

Response

{
  "user": {
    "id": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "ada@example.com",
    "username": "ada_lovelace",
    "display_name": null,
    "avatar_url": null,
    "bio": null,
    "email_verified": false,
    "created_at": "2026-03-09T14:22:11.000Z"
  },
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfYTFiMmMzZDQiLCJpYXQiOjE3NDEwOTQ1MzEsImV4cCI6MTc0MTEzMDUzMX0.xKz9QV_placeholder"
}

Examples

curl -X POST https://api.replr.ai/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "password": "Str0ngP@ss!",
    "username": "ada_lovelace"
  }'

POST/v1/auth/login

Authenticate and receive an access / refresh token pair.

Request Body

Name	Type	Required	Description
`email`	string	Required	User email address.
`password`	string	Required	Password (min 8 characters, must include a number and uppercase letter).

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c3JfYTFiMmMzZDQiLCJpYXQiOjE3NDEwOTQ1MzEsImV4cCI6MTc0MTEzMDUzMX0.qRv_placeholder",
  "refresh_token": "rt_f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "expires_in": 36000,
  "user": {
    "id": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "ada@example.com",
    "username": "ada_lovelace",
    "display_name": "Ada Lovelace",
    "avatar_url": "https://cdn.replr.ai/avatars/usr_a1b2c3d4.webp",
    "email_verified": true
  }
}

Examples

curl -X POST https://api.replr.ai/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "password": "Str0ngP@ss!"
  }'

POST/v1/auth/verify-emailAuth Required

Verify a user's email address using the token from the verification email.

Request Body

Name	Type	Required	Description
`token`	string	Required	One-time verification token sent via email.

Response

{
  "message": "Email verified successfully.",
  "email_verified": true
}

Examples

curl -X POST https://api.replr.ai/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{ "token": "vt_7c9e6679-7425-40de-944b-e07fc1f90ae7" }'

POST/v1/auth/forgot-password

Send a password-reset email. Always returns 200 regardless of whether the email exists (prevents enumeration).

Request Body

Name	Type	Required	Description
`email`	string	Required	User email address.

Response

{
  "message": "If that email is registered, a reset link has been sent."
}

Examples

curl -X POST https://api.replr.ai/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com" }'

POST/v1/auth/reset-password

Reset a user's password using the token from the reset email.

Request Body

Name	Type	Required	Description
`token`	string	Required	One-time verification token sent via email.
`new_password`	string	Required	The new password (same requirements as registration).

Response

{
  "message": "Password has been reset successfully."
}

Examples

curl -X POST https://api.replr.ai/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "rst_550e8400-e29b-41d4-a716-446655440000",
    "new_password": "N3wSecureP@ss!"
  }'

GET/v1/auth/meAuth Required

Return the profile of the currently authenticated user.

Response

{
  "id": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "ada@example.com",
  "username": "ada_lovelace",
  "display_name": "Ada Lovelace",
  "avatar_url": "https://cdn.replr.ai/avatars/usr_a1b2c3d4.webp",
  "bio": "Building intelligent conversational agents.",
  "email_verified": true,
  "plan": "pro",
  "created_at": "2026-03-09T14:22:11.000Z",
  "updated_at": "2026-03-09T16:45:03.000Z"
}

Examples

curl https://api.replr.ai/v1/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

PUT/v1/auth/meAuth Required

Update the authenticated user's profile. Only provided fields are changed.

Request Body

Name	Type	Required	Description
`username`	string	Optional	New username (3-32 characters).
`display_name`	string	Optional	Public display name (max 64 characters).
`avatar_url`	string	Optional	URL to a profile image (must be HTTPS).
`bio`	string	Optional	Short biography (max 280 characters).

Response

{
  "id": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "ada@example.com",
  "username": "ada_lovelace",
  "display_name": "Ada L.",
  "avatar_url": "https://cdn.replr.ai/avatars/usr_a1b2c3d4.webp",
  "bio": "Building the future of AI conversations.",
  "email_verified": true,
  "plan": "pro",
  "created_at": "2026-03-09T14:22:11.000Z",
  "updated_at": "2026-03-09T18:12:44.000Z"
}

Examples

curl -X PUT https://api.replr.ai/v1/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Ada L.",
    "bio": "Building the future of AI conversations."
  }'

POST/v1/auth/api-keysAuth Required

Create a new API key. The full key is only returned once — store it securely.

Request Body

Name	Type	Required	Description
`name`	string	Required	A human-readable label for this key (e.g. "production-backend").
`scopes`	string[]	Required	Permission scopes: replrs:read, replrs:write, conversations:read, conversations:write, voice, admin.

Response

{
  "id": "key_9f86d081-884c-4d65-9a2f-af22d9a68c18",
  "name": "production-backend",
  "key": "rk_live_4f3c2b1a0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
  "scopes": [
    "replrs:read",
    "replrs:write",
    "conversations:read",
    "conversations:write"
  ],
  "created_at": "2026-03-09T19:00:00.000Z",
  "last_used_at": null
}

Examples

curl -X POST https://api.replr.ai/v1/auth/api-keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-backend",
    "scopes": ["replrs:read", "replrs:write", "conversations:read", "conversations:write"]
  }'

GET/v1/auth/api-keysAuth Required

List all API keys for the authenticated user. Keys are masked after creation.

Response

{
  "data": [
    {
      "id": "key_9f86d081-884c-4d65-9a2f-af22d9a68c18",
      "name": "production-backend",
      "key_hint": "rk_live_4f3c...5d4c",
      "scopes": [
        "replrs:read",
        "replrs:write",
        "conversations:read",
        "conversations:write"
      ],
      "created_at": "2026-03-09T19:00:00.000Z",
      "last_used_at": "2026-03-09T21:34:12.000Z"
    },
    {
      "id": "key_6fa459ea-ee8a-3ca4-894e-db77e160355e",
      "name": "staging-debug",
      "key_hint": "rk_test_8b7a...2e1f",
      "scopes": [
        "replrs:read",
        "conversations:read"
      ],
      "created_at": "2026-03-01T10:15:00.000Z",
      "last_used_at": "2026-03-08T08:22:47.000Z"
    }
  ]
}

Examples

curl https://api.replr.ai/v1/auth/api-keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

DELETE/v1/auth/api-keys/:idAuth Required

Permanently revoke an API key. Any request using this key will immediately return 401.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The API key ID (e.g. key_9f86d081-...).

Response

{
  "message": "API key revoked.",
  "id": "key_9f86d081-884c-4d65-9a2f-af22d9a68c18",
  "revoked_at": "2026-03-09T22:01:30.000Z"
}

Examples

curl -X DELETE https://api.replr.ai/v1/auth/api-keys/key_9f86d081-884c-4d65-9a2f-af22d9a68c18 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

POST/v1/auth/export-dataAuth Required

Request a full export of your account data (GDPR). You will receive a download link via email when the export is ready.

Response

{
  "message": "Data export requested. You will receive an email with a download link within 24 hours.",
  "export_id": "exp_c56a4180-65aa-42ec-a945-5fd21dec0538",
  "status": "processing",
  "requested_at": "2026-03-09T22:10:00.000Z"
}

Examples

curl -X POST https://api.replr.ai/v1/auth/export-data \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

DELETE/v1/auth/meAuth Required

Permanently delete your account and all associated data. This action cannot be undone.

Response

{
  "message": "Account scheduled for deletion. All data will be purged within 30 days.",
  "deleted_at": "2026-03-09T23:59:59.000Z",
  "grace_period_ends": "2026-04-08T23:59:59.000Z"
}

Examples

curl -X DELETE https://api.replr.ai/v1/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Name

Type

Required

Description

email

string

Required

User email address.

password

string

Required

Password (min 8 characters, must include a number and uppercase letter).

username

string

Required

Unique username (3-32 characters, alphanumeric and underscores).

{ "user": { "id": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "email": "ada@example.com", "username": "ada_lovelace", "display_name": null, "avatar_url": null, "bio": null, "email_verified": false, "created_at": "2026-03-09T14:22:11.000Z" }, "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfYTFiMmMzZDQiLCJpYXQiOjE3NDEwOTQ1MzEsImV4cCI6MTc0MTEzMDUzMX0.xKz9QV_placeholder" }

Name

Type

Required

Description

email

string

Required

User email address.

password

string

Required

Password (min 8 characters, must include a number and uppercase letter).

{ "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c3JfYTFiMmMzZDQiLCJpYXQiOjE3NDEwOTQ1MzEsImV4cCI6MTc0MTEzMDUzMX0.qRv_placeholder", "refresh_token": "rt_f47ac10b-58cc-4372-a567-0e02b2c3d479", "expires_in": 36000, "user": { "id": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "email": "ada@example.com", "username": "ada_lovelace", "display_name": "Ada Lovelace", "avatar_url": "https://cdn.replr.ai/avatars/usr_a1b2c3d4.webp", "email_verified": true } }

Name

Type

Required

Description

token

string

Required

One-time verification token sent via email.

curl -X POST https://api.replr.ai/v1/auth/verify-email \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -d '{ "token": "vt_7c9e6679-7425-40de-944b-e07fc1f90ae7" }'

Name

Type

Required

Description

email

string

Required

User email address.

Name

Type

Required

Description

token

string

Required

One-time verification token sent via email.

new_password

string

Required

The new password (same requirements as registration).

curl -X POST https://api.replr.ai/v1/auth/reset-password \ -H "Content-Type: application/json" \ -d '{ "token": "rst_550e8400-e29b-41d4-a716-446655440000", "new_password": "N3wSecureP@ss!" }'

{ "id": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "email": "ada@example.com", "username": "ada_lovelace", "display_name": "Ada Lovelace", "avatar_url": "https://cdn.replr.ai/avatars/usr_a1b2c3d4.webp", "bio": "Building intelligent conversational agents.", "email_verified": true, "plan": "pro", "created_at": "2026-03-09T14:22:11.000Z", "updated_at": "2026-03-09T16:45:03.000Z" }

Name

Type

Required

Description

username

string

Optional

New username (3-32 characters).

display_name

string

Optional

Public display name (max 64 characters).

avatar_url

string

Optional

URL to a profile image (must be HTTPS).

bio

string

Optional

Short biography (max 280 characters).

{ "id": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "email": "ada@example.com", "username": "ada_lovelace", "display_name": "Ada L.", "avatar_url": "https://cdn.replr.ai/avatars/usr_a1b2c3d4.webp", "bio": "Building the future of AI conversations.", "email_verified": true, "plan": "pro", "created_at": "2026-03-09T14:22:11.000Z", "updated_at": "2026-03-09T18:12:44.000Z" }

curl -X PUT https://api.replr.ai/v1/auth/me \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "display_name": "Ada L.", "bio": "Building the future of AI conversations." }'

Name

Type

Required

Description

name

string

Required

A human-readable label for this key (e.g. "production-backend").

scopes

string[]

Required

Permission scopes: replrs:read, replrs:write, conversations:read, conversations:write, voice, admin.

{ "id": "key_9f86d081-884c-4d65-9a2f-af22d9a68c18", "name": "production-backend", "key": "rk_live_4f3c2b1a0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c", "scopes": [ "replrs:read", "replrs:write", "conversations:read", "conversations:write" ], "created_at": "2026-03-09T19:00:00.000Z", "last_used_at": null }

curl -X POST https://api.replr.ai/v1/auth/api-keys \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "production-backend", "scopes": ["replrs:read", "replrs:write", "conversations:read", "conversations:write"] }'

{ "data": [ { "id": "key_9f86d081-884c-4d65-9a2f-af22d9a68c18", "name": "production-backend", "key_hint": "rk_live_4f3c...5d4c", "scopes": [ "replrs:read", "replrs:write", "conversations:read", "conversations:write" ], "created_at": "2026-03-09T19:00:00.000Z", "last_used_at": "2026-03-09T21:34:12.000Z" }, { "id": "key_6fa459ea-ee8a-3ca4-894e-db77e160355e", "name": "staging-debug", "key_hint": "rk_test_8b7a...2e1f", "scopes": [ "replrs:read", "conversations:read" ], "created_at": "2026-03-01T10:15:00.000Z", "last_used_at": "2026-03-08T08:22:47.000Z" } ] }

Name

Type

Required

Description

id

string

Required

The API key ID (e.g. key_9f86d081-...).

{ "message": "Data export requested. You will receive an email with a download link within 24 hours.", "export_id": "exp_c56a4180-65aa-42ec-a945-5fd21dec0538", "status": "processing", "requested_at": "2026-03-09T22:10:00.000Z" }