API Reference

BastionAuth provides a RESTful API for all authentication operations.

Base URL

https://api.bastionauth.dev/api/v1

For self-hosted deployments, replace with your API URL.

Authentication

Most endpoints require authentication via Bearer token:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://api.bastionauth.dev/api/v1/users/me

Endpoints

Authentication

Sign Up

POST /auth/sign-up

Create a new user account.

Request Body:

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "firstName": "John",
  "lastName": "Doe"
}

Response:

{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "emailVerified": false
  },
  "accessToken": "eyJ...",
  "refreshToken": "eyJ..."
}

Sign In

POST /auth/sign-in

Authenticate an existing user.

Request Body:

{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}

Response:

{
  "user": { ... },
  "accessToken": "eyJ...",
  "refreshToken": "eyJ..."
}

Sign Out

POST /auth/sign-out

Invalidate the current session.

Headers: Authorization: Bearer ACCESS_TOKEN

Refresh Token

POST /auth/refresh

Get a new access token using a refresh token.

Request Body:

{
  "refreshToken": "eyJ..."
}

Users

Get Current User

GET /users/me

Get the authenticated user's profile.

Headers: Authorization: Bearer ACCESS_TOKEN

Response:

{
  "id": "uuid",
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "emailVerified": true,
  "mfaEnabled": false,
  "createdAt": "2024-01-01T00:00:00Z"
}

Update Profile

PATCH /users/me

Update the authenticated user's profile.

Request Body:

{
  "firstName": "Jane",
  "lastName": "Smith"
}

Change Password

POST /users/me/change-password

Change the authenticated user's password.

Request Body:

{
  "currentPassword": "OldPassword123!",
  "newPassword": "NewPassword456!"
}

MFA (Multi-Factor Authentication)

Enable MFA

POST /auth/mfa/enable

Generate MFA setup data (TOTP secret and QR code).

Response:

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qrCode": "data:image/png;base64,...",
  "backupCodes": ["12345678", "87654321", ...]
}

Verify MFA

POST /auth/mfa/verify

Verify MFA code and complete setup.

Request Body:

{
  "code": "123456"
}

Organizations

List Organizations

GET /organizations

Get all organizations the user belongs to.

Create Organization

POST /organizations

Create a new organization.

Request Body:

{
  "name": "My Company",
  "slug": "my-company"
}

Invite Member

POST /organizations/:orgId/invitations

Invite a user to join the organization.

Request Body:

{
  "email": "newmember@example.com",
  "role": "member"
}

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "AUTH_001",
    "message": "Invalid credentials",
    "statusCode": 401
  }
}

Error Codes

Rate Limits

Rate limit headers are included in responses:

• X-RateLimit-Limit: Maximum requests
• X-RateLimit-Remaining: Remaining requests
• X-RateLimit-Reset: Reset timestamp

Webhooks

BastionAuth can send webhooks for important events:

• user.created
• user.updated
• user.deleted
• session.created
• session.revoked
• organization.created
• organization.member.added
• organization.member.removed

Configure webhooks in the Admin Dashboard under Settings → Webhooks.