Appearance
Current authenticated user identity
GET
/api/auth/me
Returns the authenticated user's identity, admin status, and provider. Used by the SPA on every page load to determine auth state, populate the navbar, and guard routes. Returns 401 when not authenticated.
Authorizations
cookieAuth
Type
API Key (cookie: _vulcan_session)
or
tokenAuth
Personal access token authentication. Send via Authorization header: Authorization: Token vulcan_xxx. Tokens are SHA-256 hashed server-side (never stored in plaintext). Scopes: read (GET), write (mutations), admin (everything). Create tokens via Settings → API Tokens in the web UI.
Type
HTTP (token)
Responses
Authenticated user identity
application/json
JSON "id": 42, "name": "Jane Doe", "email": "jane@example.com", "admin": false, "provider": null
{
}
Authenticate with email and password
POST
/api/auth/login
Creates a session for local (email/password) authentication. Returns the authenticated user identity on success. Sets a session cookie for subsequent requests. OIDC and LDAP providers use their own OAuth callback flows.
Request Body
application/json
JSON "email": "jane@example.com", "password": "S3cure!#Pass001"
{
}
Responses
Authentication successful — session created
application/json
JSON "id": 42, "name": "Jane Doe", "email": "jane@example.com", "admin": false, "provider": null
{
}
Sign out and destroy session
DELETE
/api/auth/logout
Destroys the current session. Subsequent requests require re-authentication. Returns a confirmation message.
Authorizations
cookieAuth
Type
API Key (cookie: _vulcan_session)
or
tokenAuth
Personal access token authentication. Send via Authorization header: Authorization: Token vulcan_xxx. Tokens are SHA-256 hashed server-side (never stored in plaintext). Scopes: read (GET), write (mutations), admin (everything). Create tokens via Settings → API Tokens in the web UI.
Type
HTTP (token)
Responses
Session destroyed
application/json
JSON "message": "Signed out successfully"
{
}
Delete the signed-in user's own account
DELETE
/users
Permanently deletes the current user's account and signs them out. Local-credential users must re-authenticate with current_password (OWASP ASVS 3.7.1); provider-managed and SSO-created accounts are exempt — their identity provider owns re-authentication. Blocked with 422 when the user is the only system administrator or the only admin of any project (transfer the admin role first). Repeated wrong passwords count toward account lockout and return 423 once locked.
Authorizations
cookieAuth
Type
API Key (cookie: _vulcan_session)
or
tokenAuth
Personal access token authentication. Send via Authorization header: Authorization: Token vulcan_xxx. Tokens are SHA-256 hashed server-side (never stored in plaintext). Scopes: read (GET), write (mutations), admin (everything). Create tokens via Settings → API Tokens in the web UI.
Type
HTTP (token)
Request Body
application/json
JSON "user": { "current_password": "MyCurrentP@ssw0rd!" }
{
}
Responses
Account deleted and session ended
application/json
JSON "toast": { "title": "Account deleted.", "message": [ "Account deleted successfully." ], "variant": "success" }
{
}
Get current user profile (Devise edit)
GET
/users/edit
Returns the authenticated user's profile as JSON. This is the Devise registration edit endpoint with JSON support. The SPA may prefer GET /api/auth/me which returns the same CurrentUserResponse shape. Requires authentication.
Authorizations
cookieAuth
Type
API Key (cookie: _vulcan_session)
or
tokenAuth
Personal access token authentication. Send via Authorization header: Authorization: Token vulcan_xxx. Tokens are SHA-256 hashed server-side (never stored in plaintext). Scopes: read (GET), write (mutations), admin (everything). Create tokens via Settings → API Tokens in the web UI.
Type
HTTP (token)
Responses
Current user profile
application/json
JSON "id": 42, "name": "Jane Doe", "email": "jane@example.com", "admin": false, "provider": null
{
}
Reset password using token from email
PUT
/users/password
Resets the user's password using the token from the reset email. On success, signs the user in and returns a success toast. On failure (invalid token, mismatched passwords, complexity violation), returns 422 with error details.
Request Body
application/json
JSON "user": { "reset_password_token": "abc123def456", "password": "N3wS3cure!#Pass", "password_confirmation": "N3wS3cure!#Pass" }
{
}
Responses
Password reset successfully — user signed in
application/json
JSON "toast": { "title": "Password reset.", "message": [ "Your password has been changed successfully. You are now signed in." ], "variant": "success" }
{
}
Request password reset instructions
POST
/users/password
Sends a password reset email to the given address. In paranoid mode (default), always returns success — even if the email is not registered — to prevent email enumeration. Blank email returns 422.
Request Body
application/json
JSON "user": { "email": "jane@example.com" }
{
}
Responses
Instructions sent (or paranoid success)
application/json
JSON "toast": { "title": "Instructions sent.", "message": [ "If your email address exists in our database, you will receive a password recovery link at your email address in a few minutes." ], "variant": "success" }
{
}
Validate a password reset token
GET
/users/password/edit
Checks whether a password reset token is valid and not expired. The SPA calls this when the user follows the reset link to determine whether to show the reset form or an error message. Returns the minimum password length for client-side validation.
Parameters
Query Parameters
reset_password_token*
The raw reset token from the email link.
Type
Requiredstring
Example
"abc123def456"Responses
Token is valid
application/json
JSON "valid": true, "minimum_password_length": 15
{
}
Resend email confirmation instructions
POST
/users/confirmation
Sends a new confirmation email to the given address. In paranoid mode (default), always returns success — even if the email is not registered or already confirmed — to prevent email enumeration. Blank email returns 422.
Request Body
application/json
JSON "user": { "email": "jane@example.com" }
{
}
Responses
Instructions sent (or paranoid success)
application/json
JSON "toast": { "title": "Instructions sent.", "message": [ "If your email address exists in our database, you will receive an email with instructions for how to confirm your email address in a few minutes." ], "variant": "success" }
{
}
Request account unlock instructions
POST
/users/unlock
Sends unlock instructions email to the given address. In paranoid mode (default), always returns success — even if the email is not registered or the account is not locked — to prevent email enumeration. Blank email returns 422. Requires lockout to be enabled with an email-based unlock strategy (both or email).
Request Body
application/json
JSON "user": { "email": "jane@example.com" }
{
}
Responses
Instructions sent (or paranoid success)
application/json
JSON "toast": { "title": "Instructions sent.", "message": [ "If your email address exists in our database, you will receive an email with instructions for how to unlock your account in a few minutes." ], "variant": "success" }
{
}