Skip to main content

Authentication API Reference

Complete reference for the Authentication API endpoints.

Base URL​

https://api.orcarail.com/api/v1

Sign Up​

Accounts are created only after the email address is verified with a one-time code. Disposable email domains are rejected (422, errors.email: "disposableEmail").

Send a sign-up code​

POST /auth/email/register/send-code
ParameterTypeRequiredDescription
emailstringYesUser email address

Returns 200. A 6-digit code is emailed. An email that already has an account returns 422 with errors.email: "emailAlreadyExists".

Verify the code​

POST /auth/email/register/verify-code
ParameterTypeRequiredDescription
emailstringYesUser email address
codestringYes6-digit code from email

Creates the account and returns the same body as Login (token, refreshToken, tokenExpires, user).

Confirm New Email​

Confirm a new email address after the user requested an email change.

POST /auth/email/confirm/new

Authentication​

  • None required

Request Body​

ParameterTypeRequiredDescription
hashstringYesConfirmation token from email

Response​

204 No Content

Login​

Authenticate a user and receive a JWT token.

POST /auth/email/login

Authentication​

  • None required

Request Body​

ParameterTypeRequiredDescription
emailstringYesUser email address
passwordstringYesUser password

A blocked account returns 422 with errors.email: "accountBlocked".

Response​

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "refresh_token_here",
  "tokenExpires": 3600,
  "user": {
    "id": 1,
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe"
  }
}

Refresh Token​

Get a new access token using a refresh token.

POST /auth/refresh

Authentication​

  • Bearer Token (JWT) - Refresh token required

Response​

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "new_refresh_token_here",
  "tokenExpires": 3600
}

Get Current User​

Get information about the authenticated user.

GET /auth/me

Authentication​

  • Bearer Token (JWT) - Required

Response​

{
  "id": 1,
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "role": "user",
  "status": "active",
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Update Current User​

Update the authenticated user's information.

PATCH /auth/me

Authentication​

  • Bearer Token (JWT) - Required

Request Body​

All fields are optional. Only include fields to update.

ParameterTypeRequiredDescription
firstNamestringNoUpdated first name
lastNamestringNoUpdated last name
emailstringNoUpdated email (requires confirmation)

Response​

{
  "id": 1,
  "email": "[email protected]",
  "firstName": "Jane",
  "lastName": "Doe",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Logout​

Log out and invalidate the current session.

POST /auth/logout

Authentication​

  • Bearer Token (JWT) - Required

Response​

204 No Content

Delete Current User​

Permanently delete the authenticated user's account (soft delete).

DELETE /auth/me

Authentication​

  • Bearer Token (JWT) - Required

Response​

204 No Content

Forgot Password​

Request a password reset email.

POST /auth/forgot/password

Authentication​

  • None required

Request Body​

ParameterTypeRequiredDescription
emailstringYesUser email address

Response​

204 No Content

A password reset email will be sent to the provided email address.

Reset Password​

Reset password using a reset token.

POST /auth/reset/password

Authentication​

  • None required

Request Body​

ParameterTypeRequiredDescription
hashstringYesReset token from email
passwordstringYesNew password

Response​

204 No Content

Status Codes​

Status CodeDescription
200Success
204No Content
400Bad Request
401Unauthorized
404Not Found
500Internal Server Error

Error Response Format​

{
  "statusCode": 400,
  "message": "Invalid email or password",
  "error": "Bad Request"
}

Token Expiration​

  • Access Token: Expires after 1 hour (3600 seconds)
  • Refresh Token: Expires after 7 days

When a token expires, you'll receive a 401 Unauthorized response. Use the refresh token endpoint to get a new access token.

See Also​