Skip to content

Profile Management

View raw .md

The JSON endpoints a signed-in user manages their own profile with: details, password, photo, account deletion, email verification, sessions and the newsletter, plus the public settings API.

On this page

Quick Reference#

All endpoints are JSON-only (no views or redirects) and sit under the configured route prefix. Every one needs auth:sanctum unless the table says otherwise.

Method and URI Needs Does
PUT user/profile Updates the profile fields.
PUT user/password Changes the password.
POST or DELETE user Schedules the account for deletion.
POST user/profile-photo, DELETE user/profile-photo profile-photos Uploads or removes the photo.
GET email/verify/{id}/{hash} email-verification, no auth Verifies the address through a signed link.
POST email/verification-notification email-verification Sends a new verification link.
GET settings no auth The public settings the client reads before sign-in.
GET user/newsletter, PUT user/newsletter newsletter-subscription Reads or changes the subscription.
GET sessions, DELETE sessions/{token}, DELETE sessions/other sessions Lists and revokes sessions.

Update Profile#

Updates the authenticated user's profile information.

Property Value
Method PUT
URI user/profile
Auth auth:sanctum
Controller ProfileController@update
Request UpdateProfileRequest
Response UserResource

Fields#

Field Type Rules
name string Required (nullable for guests), min:2, max:255
email string Nullable, valid email, max:255, unique per user table
phone string Nullable, max:20, E.164 format (requires extended-profile feature)
timezone string Nullable, valid IANA timezone (requires extended-profile or timezones feature)
locale string Nullable, must be in magic-starter.supported_locales (requires extended-profile feature)

Guest users may additionally pass password and password_confirmation to upgrade their account in a single call. The password must be at least 8 characters with letters, numbers, and mixed case. When a guest provides an email/phone and a password, they are automatically converted to a full user (is_guest becomes false). The conversion dispatches AnilcanCakir\MagicStarter\Events\GuestConverted once, after the transaction commits, from this endpoint or from a guest setting a first password; listen to it for anything a host does for a new registered account, such as a welcome message.

When the email changes and the email-verification feature is enabled, email_verified_at is reset to null and a new verification notification is sent.

Request Example#

text
PUT /user/profile
Authorization: Bearer {token}
Content-Type: application/json

{
    "name": "Jane Doe",
    "email": "[email protected]",
    "phone": "+15551234567",
    "timezone": "America/New_York",
    "locale": "en"
}

Response Example#

json
{
    "data": {
        "id": 1,
        "name": "Jane Doe",
        "email": "[email protected]",
        "phone": "+15551234567",
        "is_guest": false,
        "email_verified_at": "2025-01-15T10:30:00.000000Z",
        "locale": "en",
        "timezone": "America/New_York",
        "profile_photo_url": null,
        "two_factor_enabled": false,
        "created_at": "2025-01-10T08:00:00.000000Z",
        "updated_at": "2025-01-15T10:30:00.000000Z"
    }
}

Update Password#

Updates the authenticated user's password.

Property Value
Method PUT
URI user/password
Auth auth:sanctum
Controller ProfileController@updatePassword
Request UpdatePasswordRequest

Fields#

Field Type Rules
current_password string Required (optional for guest users without a password)
password string Required, min:8, letters + numbers + mixed case, confirmed
password_confirmation string Required

The current_password is verified against the stored hash via Hash::check(). Guest users who have no password set yet can skip the current_password field. An account with no password at all (a social-only one) answers 422 password_not_set; it sets its first password through Set a Password.

Request Example#

text
PUT /user/password
Authorization: Bearer {token}
Content-Type: application/json

{
    "current_password": "OldP@ssw0rd",
    "password": "NewP@ssw0rd",
    "password_confirmation": "NewP@ssw0rd"
}

Response Example#

json
{
    "data": null,
    "message": "Password updated successfully."
}

Delete Account#

Schedules the authenticated user's account for deletion. Nothing is deleted in the request: every token is revoked now and the account is purged after the grace period, and signing in again before then cancels it. With immediately: true the purge is queued at once instead. See Account Deletion for the pipeline.

Property Value
Method POST or DELETE
URI user/
Auth auth:sanctum
Controller ProfileController@destroy
Request DeleteAccountRequest
Response 202 Accepted

Fields#

Field Type Rules
password string Required for a user with a password
code string A current TOTP code, for a password-less user with confirmed 2FA
confirmation_token string A step-up token from the social confirm flow, for a password-less user
immediately boolean Optional. true queues the purge now instead of after the grace period

A user with a password confirms with it. A guest without a password needs no proof. Any other password-less user sends code or confirmation_token, or the request answers 422 step_up_required.

Request Example#

text
DELETE /user/
Authorization: Bearer {token}
Content-Type: application/json

{
    "password": "CurrentP@ssw0rd"
}

Response#

202 Accepted with data.deletion_scheduled_at and a message. With immediately: true the body also carries data.immediate: true and the deletion_immediate message; without it the body is exactly the scheduled one. The refusals and the step-up are the same either way, and nothing is queued when one of them answers. An owned team that another member belongs to, or that holds a live subscription, answers 422 with code owns_shared_teams or team_has_active_subscription and the team_ids to resolve first; with account_deletion.hand_on_shared_teams on, a shared team is no longer a reason to refuse, and the purge hands it on. A live subscription billing the user directly answers 422 subscription_active with an empty team_ids, unless account_deletion.billing is release: then the request is accepted, the Stripe subscription is cancelled with no proration, and data.billing lists what was cancelled and which store subscriptions (store) the user still has to cancel in the store. See Releasing Billing.


Profile Photo#

Available when the profile-photos feature is enabled in config/magic-starter.php.

Upload Profile Photo#

Property Value
Method POST
URI user/profile-photo
Auth auth:sanctum
Controller ProfilePhotoController@update
Request UpdateProfilePhotoRequest
Response UserResource
Field Type Rules
photo file Required, image, max:1024 KB (1 MB)

The photo is stored on the disk configured by magic-starter.profile_photo_disk (falls back to filesystems.default, typically public) with no visibility or ACL call, so it is as public as that disk's own visibility setting: set 'visibility' => 'public' on an S3 disk that serves its objects by ACL, or serve the bucket by policy. The storage path is controlled by magic-starter.profile_photo_path (default: profile-photos). If a previous photo exists, it is deleted from the disk before storing the new one.

Request Example

text
POST /user/profile-photo
Authorization: Bearer {token}
Content-Type: multipart/form-data

photo: (binary image file)

Response Example

json
{
    "data": {
        "id": 1,
        "name": "Jane Doe",
        "profile_photo_url": "https://your-app.com/storage/profile-photos/abc123.jpg",
        "..."
    }
}

Delete Profile Photo#

Property Value
Method DELETE
URI user/profile-photo
Auth auth:sanctum
Controller ProfilePhotoController@delete
Response UserResource

Removes the photo file from disk and sets profile_photo_path to null. The profile_photo_url in the response is null again (see HasProfilePhoto Trait).

Request Example

text
DELETE /user/profile-photo
Authorization: Bearer {token}

HasProfilePhoto Trait#

The HasProfilePhoto trait (AnilcanCakir\MagicStarter\Traits\HasProfilePhoto) provides the profile_photo_url accessor used by UserResource.

profilePhotoUrl Accessor#

getProfilePhotoUrlAttribute(): ?string

If profile_photo_path is set, returns the public URL from the configured filesystem disk (magic-starter.profile_photo_disk). If the disk driver supports the url() method, it generates the full URL; otherwise it returns the raw path.

When no photo is stored it returns null, and the client draws its own initials. A generated image would cost a third-party round trip per avatar, send the person's name to that third party, fail offline, arrive in colours the client's design system did not choose, and be impossible to tell apart from a real upload.

Configuration#

Config Key Default Description
magic-starter.profile_photo_disk filesystems.default Filesystem disk for photo storage
magic-starter.profile_photo_path profile-photos Storage directory within the disk

Email Verification#

Available when the email-verification feature is enabled.

Verify Email Address#

Property Value
Method GET
URI email/verify/{id}/{hash}
Middleware signed:relative (no auth required)
Route Name verification.verify
Controller EmailVerificationController@verify

This is a public endpoint protected by a signed URL (not auth:sanctum). The {hash} parameter is a SHA-1 of the user's email address. The link is validated to ensure it matches the user's current email, preventing reuse after an email change.

The mailed link depends on magic-starter.frontend_url. Without it, the mail carries this signed route and the API answers it with the JSON below. With it, the mail opens the client's verify page, {frontend}/auth/verify-email?id=&hash=&expires=&signature=, and that page replays the four values as GET email/verify/{id}/{hash}?expires=&signature= against the API. The signature is relative: it covers the path and expiry, not the host, because the mail goes out from whichever host the request came in on (a staff resend comes from the panel host) and the client calls the API host. magic_starter 0.0.53 and later ships that page.

Status Response
Success 200 {"message": "Email verified successfully."}
Already verified 200 {"message": "Email already verified."}
Invalid hash 403 {"message": "Invalid verification link."}
User not found 404
Invalid signature 403 (Laravel signed middleware)

Send Verification Notification#

Property Value
Method POST
URI email/verification-notification
Auth auth:sanctum
Middleware throttle:magic-starter-email-verification
Route Name verification.send
Controller EmailVerificationController@sendVerificationNotification

Sends a signed verification link to the authenticated user's email address.

Status Response
Sent 202 {"message": "Verification link sent."}
Already verified 200 {"message": "Email already verified."}
No email address 400 {"message": "No email address to verify."}

Request Example

text
POST /email/verification-notification
Authorization: Bearer {token}

Settings API#

A public, unauthenticated endpoint that exposes feature flags and locale/timezone defaults for client bootstrapping.

Property Value
Method GET
URI settings
Middleware throttle:magic-starter-settings
Controller SettingsController@index

This endpoint intentionally does not require authentication. It only exposes allowlisted values and never leaks internal configuration (URLs, token TTLs, model classes, file paths).

Response Example#

json
{
    "supported_locales": ["en", "tr", "de"],
    "features": {
        "registration": true,
        "teams": true,
        "social_login": false,
        "email_verification": true,
        "guest_auth": false,
        "phone_otp": false,
        "newsletter": true,
        "extended_profile": true,
        "two_factor_authentication": true,
        "sessions": true,
        "profile_photos": true,
        "notifications": true,
        "timezones": true,
        "releases": false
    },
    "auth": {
        "email": true,
        "phone": false
    },
    "defaults": {
        "locale": "en",
        "timezone": "UTC"
    }
}

Newsletter Subscription#

Available when the newsletter-subscription feature is enabled.

Show Subscription Status#

Property Value
Method GET
URI user/newsletter
Auth auth:sanctum
Controller NewsletterController@show

Returns the status of the user's own subscription. The subscription belongs to the user, not to an address, so it keeps working after the user changes their email.

Response Example (subscribed)

json
{
    "subscribed": true,
    "source": "profile",
    "subscribed_at": "2025-03-10T14:00:00.000000Z"
}

Response Example (not subscribed)

json
{
    "subscribed": false
}

Update Subscription#

Property Value
Method PUT
URI user/newsletter
Auth auth:sanctum
Controller NewsletterController@update
Field Type Rules
subscribe boolean Required

Subscribing records the user's consent with source set to profile and sends the confirmation mail. Unsubscribing withdraws the consent without deleting the record. Requires the user to have an email address; returns 400 otherwise. The response shape is the same as GET user/newsletter, and subscribed_at is the time of the latest consent.

Request Example

text
PUT /user/newsletter
Authorization: Bearer {token}
Content-Type: application/json

{
    "subscribe": true
}

Response Example

json
{
    "subscribed": true,
    "source": "profile",
    "subscribed_at": "2025-03-10T14:00:00.000000Z"
}

Error: No Email

json
// 400
{
    "message": "Email address required for newsletter subscription."
}

One newsletter_subscribers row per user (user_id is unique and the row goes with the user). Besides email (a copy kept in step with the user's), is_active and source, the row carries the consent behind it:

Column Meaning
consented_at When the user last gave consent
consent_version magic-starter.newsletter.consent_version, the version of your consent wording at that moment
consent_source Where the consent was given: profile or registration (the subscribe_newsletter flag of POST auth/register)
unsubscribed_at When the consent was withdrawn, null while it stands
unsubscribe_token The secret of the unsubscribe link, minted once and never rotated; hidden from serialization

Raise consent_version (MAGIC_STARTER_NEWSLETTER_CONSENT_VERSION) whenever the wording users agreed to changes, so each row says which text it rests on. Rows written before this record existed read consent_version pre-e5a, with consented_at set to their creation time.

Subscribing again after a withdrawal reactivates the same row: the token stays, unsubscribed_at is cleared, and consented_at, consent_version and consent_source are rewritten with the new consent. Subscribing while already subscribed changes nothing but the consent record, and sends no second mail.

Confirmation Mail#

Each time a user goes from not subscribed to subscribed, NewsletterSubscribedNotification is queued to their address, in their locale. It states the date of the consent and carries the unsubscribe link. It is a notice, not a double opt-in: the subscription is already active when it is sent. The queue worker has to be running, and a transport failure fails the queued job, not the request that recorded the consent. The mail copy lives in lang/{en,tr}/newsletter.php under magic-starter::newsletter.mail.

One-Click Unsubscribe#

Every newsletter mail can carry the same link, built from the row's token:

Method URI What it does
GET /newsletter/unsubscribe/{token} Shows a confirmation page, or says it is already done. Changes nothing
POST /newsletter/unsubscribe/{token} Withdraws the consent and answers 200 with the result page

The two routes are magic-starter.newsletter.unsubscribe and magic-starter.newsletter.unsubscribe.store. They are registered with the feature on, outside magic-starter.route_prefix and outside every middleware group, because the URL is baked into mail that was already sent. The token is the only credential: there is no session, cookie or CSRF token, and an unknown token answers 404 with a page that names nothing.

GET is deliberately read-only, since mail scanners and link previews follow every link. The POST is the one a mail provider sends for RFC 8058 one-click unsubscribe, so a newsletter mail should carry both headers:

text
List-Unsubscribe: <https://api.example.com/newsletter/unsubscribe/{token}>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The POST accepts any body (List-Unsubscribe=One-Click included), is idempotent, and is throttled per token by magic-starter-newsletter-unsubscribe (10 per minute); the page is throttled per IP by magic-starter-newsletter-unsubscribe-page (60 per minute). The page renders in the owner's locale and sends Referrer-Policy: no-referrer.

Marketing Audience#

NewsletterSubscriber::marketable() is the only audience a sender may use. It selects rows that are active, have a consented_at, have no unsubscribed_at and belong to a user:

php
use AnilcanCakir\MagicStarter\Models\NewsletterSubscriber;

NewsletterSubscriber::query()->marketable()->each(function (NewsletterSubscriber $subscriber): void {
    // send, with $subscriber->unsubscribe_token in the footer link
});

The package sends no campaigns itself.

Email Changes and Deletion#

The subscription follows its user. When a user's email changes through the profile action, any $user->update() or the admin panel's user form, the row's address is rewritten to match. Deleting the account deletes the row with its audit rows, see Account Deletion.

A row written by address alone, as the previous release did, is claimed by the user whose address matches the first time that user reads or changes their subscription, and keeps working while old and new code run side by side during a deploy.


Session Management#

Available when the sessions feature is enabled. Sessions are Sanctum personal access tokens.

List Sessions#

Property Value
Method GET
URI sessions
Auth auth:sanctum
Controller SessionController@index
Response SessionResource collection

Returns all active tokens for the authenticated user.

agent is parsed from the stored user agent by SessionAgent. browser, platform and app are EMPTY strings when it cannot name them, never a word: this is a package, and a literal here would be English frozen into every consumer's UI. They are independent, so a partially readable agent reports the half it read. Show your own translated label when all of them are empty.

app names a NATIVE client and is empty for a browser. magic's network provider sends <App Name> (Flutter; <platform>) by default, and this reads it: platform comes back iOS, browser stays empty because a native client is not a browser, and is_mobile is decided by the platform token rather than by a substring sweep. Render platform with whichever of browser and app is present; they are mutually exclusive by construction.

Before this, a native agent matched none of the browser patterns and none of the platform patterns, so both came back empty, is_mobile came back false, and is_desktop therefore came back TRUE: a phone's own session rendered as a browser session on an unknown desktop.

Response Example

json
{
    "data": [
        {
            "id": 42,
            "ip_address": "192.168.1.10",
            "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
            "agent": {
                "browser": "Chrome",
                "platform": "Mac",
                "app": "",
                "is_desktop": true,
                "is_mobile": false
            },
            "location": {
                "city": "Istanbul",
                "country": "TR"
            },
            "is_current_device": true,
            "last_used_at": "2025-03-25T09:00:00.000000Z",
            "created_at": "2025-03-20T08:00:00.000000Z"
        },
        {
            "id": 38,
            "ip_address": "10.0.0.5",
            "user_agent": "Acme (Flutter; iOS)",
            "agent": {
                "browser": "",
                "platform": "iOS",
                "app": "Acme",
                "is_desktop": false,
                "is_mobile": true
            },
            "location": null,
            "is_current_device": false,
            "last_used_at": "2025-03-18T15:00:00.000000Z",
            "created_at": "2025-03-15T12:00:00.000000Z"
        }
    ]
}

Revoke a Specific Session#

Property Value
Method DELETE
URI sessions/{token}
Auth auth:sanctum
Controller SessionController@destroy
Request ConfirmPasswordRequest

Requires password confirmation. The {token} parameter is the token ID. Returns 404 if the token does not belong to the authenticated user.

Request Example

text
DELETE /sessions/38
Authorization: Bearer {token}
Content-Type: application/json

{
    "password": "CurrentP@ssw0rd"
}

Response Example

json
{
    "data": null,
    "message": "Session revoked successfully."
}

Revoke All Other Sessions#

Property Value
Method DELETE
URI sessions/other
Auth auth:sanctum
Controller SessionController@destroyOther
Request DestroyOtherSessionsRequest (extends ConfirmPasswordRequest)

Deletes all tokens except the one making the request. Requires password confirmation. Guest users without a password may skip the password field.

Request Example

text
DELETE /sessions/other
Authorization: Bearer {token}
Content-Type: application/json

{
    "password": "CurrentP@ssw0rd"
}

Response Example

json
{
    "data": null,
    "message": "Other sessions revoked successfully."
}

Extended Profile#

When the extended-profile feature is enabled in config/magic-starter.php, the profile update endpoint (PUT user/profile) accepts additional fields:

Field Type Description
phone string Phone number in E.164 format (e.g., +15551234567), max 20 chars
locale string Must be one of the values in magic-starter.supported_locales
timezone string Valid IANA timezone identifier (e.g., America/New_York)

The timezone field is also available when only the timezones feature is enabled (without extended-profile), as determined by Features::hasTimezoneOrExtendedProfileFeatures().

These fields are validated and stored by the UpdateUserProfile action. The UserResource always includes locale, timezone, and phone in its response regardless of the feature flag -- the feature flag only controls whether the update endpoint accepts these fields.

Configuration#

Enable the feature in config/magic-starter.php:

php
'features' => [
    Features::extendedProfile(),
    // ...
],

'supported_locales' => ['en', 'tr', 'de'],

Publishing Your Own Columns#

UserResource is not resolved through the container, so an application that adds a column to users cannot swap the resource to expose it. Register the extra fields instead, from AppServiceProvider::boot():

php
use AnilcanCakir\MagicStarter\MagicStarter;

MagicStarter::serializeUserUsing(fn ($user, $request) => [
    'subscription_tier' => $user->subscription_tier,
]);

The callback receives the user being serialised and the current request, and its return value is merged over the package's fields. Merging rather than replacing is what keeps your payload current: a field this package adds in a later release reaches you with no change on your side.

A key of yours that collides with one of the package's wins, so a value you own is yours to correct. The callback must return an array; anything else is refused by name rather than fataling inside the resource.

MagicStarter::reset() clears it, which matters in a test suite.

Gotchas#

Mistake Fix
Expecting DELETE user to remove the account at once It schedules the purge and revokes every token. Send immediately: true to queue the purge now.
Subscribing an account that has no email to the newsletter The endpoint answers 400. Collect an email first.
Sending extended profile fields with the feature off UserResource always carries locale, timezone and phone, but the update endpoint accepts them only when the feature is on.
Adding a column to users and expecting UserResource to publish it Register it with MagicStarter::serializeUserUsing(); its array is merged over the package fields.
Rendering a generated image for profile_photo_url: null null means no photo is stored. The client draws its own initials.
esc

Search index did not load.

No match for "".

Try a class like rounded-lg or a widget like WButton.