Skip to main content
POST
/
api
/
auth
/
callback
/
credentials
Login
curl --request POST \
  --url https://api.example.com/api/auth/callback/credentials \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "password": "<string>",
  "organizationId": "<string>"
}
'
{
  "success": true,
  "user": {
    "id": "<string>",
    "email": "<string>",
    "name": "<string>",
    "roles": [
      {}
    ],
    "permissions": [
      {}
    ],
    "organizationId": {},
    "organizationName": {}
  },
  "error": "<string>",
  "details": {}
}

​
Authentication

This endpoint uses NextAuth.js credentials provider for authentication.

​
Request Body

​
email
string
required
User’s email address. Must be a valid email format.
​
password
string
required
User’s password. Minimum 1 character.
​
organizationId
string
required
UUID of the organization the user belongs to.

​
Response

​
success
boolean
Indicates if the authentication was successful.
​
user
object
Authenticated user information.
​
id
string
User’s unique identifier (UUID).
​
email
string
User’s email address.
​
name
string
User’s display name or full name.
​
roles
array
Array of role names assigned to the user.
​
permissions
array
Array of permission strings for the user.
​
organizationId
string | null
UUID of the user’s organization.
​
organizationName
string | null
Name of the user’s organization.

​
Pre-Login Validation

Before attempting login, use the /api/auth/login-validation endpoint to validate user status: 
curl -X POST https://your-domain.com/api/auth/login-validation \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "organizationId": "123e4567-e89b-12d3-a456-426614174000"
  }'

​
Error Responses

​
error
string
Error message describing what went wrong.
​
details
object
Additional error details, if available.

​
Common Error Cases

Status CodeError CodeDescription
401-Invalid credentials or authentication failed
409USER_NOT_IN_ORGUser does not belong to the specified organization
409ORG_NOT_AVAILABLEOrganization is inactive or deleted
409USER_NOT_ACTIVEUser account status is not ACTIVE (e.g., PENDING_VERIFICATION)
429-Account locked due to failed login attempts (5+ failures locks for 30 minutes)

​
Login Flow

  1. User must have an ACTIVE status
  2. User must belong to the specified organization
  3. Organization must be active and not deleted
  4. Account must not be locked (due to failed attempts)
  5. Password must match the stored hash
  6. On success, failed login attempts are reset and lastLoginAt is updated
  7. On failure, failed login attempts are incremented (5+ attempts locks account for 30 minutes)
  8. All login attempts (success and failure) are logged in the audit log

​
Code Example

curl -X POST https://your-domain.com/api/auth/callback/credentials \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123",
    "organizationId": "123e4567-e89b-12d3-a456-426614174000"
  }'

​
Session Management

On successful authentication, a JWT session token is created with the following data:
  • User ID
  • Roles and permissions
  • Organization ID and name
The session uses JWT strategy and is managed by NextAuth.js.

Build docs developers (and LLMs) love

Get started for freeTalk to us