Dashboard Auth

Legacy Sign-In Redirect (Deprecated)

GET /auth/authkit

Deprecated: an old sign-in entry point, kept so existing links work. Redirects to the sign-in page, /login (keeping a same-origin next).

Authentication: None.

Query parameters

Response

302 To /login.

Headers:

Errors

Example

curl "https://api.machinemail.dev/auth/authkit"

Sign-in Callback

GET /auth/callback

Where the browser returns after a social or SSO sign-in. Checks state against the browser’s cookie, exchanges the code, links the sign-in to the MachineMail account with the same verified email (or creates one), syncs their organizations, sets the mm_session cookie and redirects to next. A person with no organization gets one, with a first API key (welcome=1, GET /auth/first-key).

When the sign-in needs one more step, the browser goes to our own screens with a mm_signin cookie: /login/organization (pick an organization) or /login/verify (verify the email with a code), or on to the organization’s SSO connection.

Failures redirect to /login?error=signin_failed (the sign-in was refused or failed), access_denied (cancelled at the provider), unverified (an unverified email matching an existing account), linked (the account is already linked to a different sign-in identity), mfa (the sign-in asked for multi-factor authentication, which MachineMail does not support), methods (the organization does not allow this sign-in method) or codes_paused (too many codes for the address recently: a verification code was not sent; try later). A callback without state (one this browser did not start) never signs anyone in: it goes to /login, or to /invite/{token} when it carries an invitation token.

Authentication: None.

Query parameters

Response

302 Signed in (Set-Cookie carries mm_session), our next screen, or back to /login with an error.

Headers:

Errors

Example

curl "https://api.machinemail.dev/auth/callback"

Preview Claim

GET /auth/claim

Called by the dashboard /claim page for a signed-in human before confirming. Pass user_code or claim_attempt_token. Returns the registration (its agent-described name is untrusted), the claim email and the sandbox inbox. 403 when the registration is bound to a different email than the signed-in user; 429 after too many lookups (per user, 10 minute window).

Authentication: the dashboard mm_session cookie.

Query parameters

Response

200 The pending registration (application/json)

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/auth/claim" \
  -H "Cookie: mm_session=$SESSION"

{
  "agent_id": "string",
  "registration_id": "string",
  "registration_type": "anonymous",
  "status": "pending_claim",
  "name": "Production",
  "client": "string",
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "inbox_id": "agent@machinemail.dev",
  "email": "agent@machinemail.dev",
  "issuer": "string",
  "agent_platform": "string",
  "created_at": "2026-10-01T12:00:00.000Z",
  "claimed_at": "2026-10-01T12:00:00.000Z",
  "revoked_at": "2026-10-01T12:00:00.000Z",
  "expires_at": "2026-10-01T12:00:00.000Z",
  "claim_email": "agent@machinemail.dev",
  "user_code_expires_at": "2026-10-01T12:00:00.000Z",
  "sandbox_inbox": {
    "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
    "inbox_id": "agent@machinemail.dev",
    "email": "agent@machinemail.dev",
    "display_name": "Support Agent",
    "client_id": "my-client-id",
    "status": "active",
    "metadata": {
      "key": "value"
    },
    "updated_at": "2026-10-01T12:00:00.000Z",
    "created_at": "2026-10-01T12:00:00.000Z",
    "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
    "ephemeral": false,
    "ttl_seconds": 1,
    "expires_at": "2026-10-01T12:00:00.000Z",
    "created_by": "api"
  }
}

Complete Claim

POST /auth/claim

Called by the dashboard /claim page for a signed-in human. Binds the agent registration to their organization, moves the sandbox inbox into their default pod (made permanent) and invalidates pre-claim tokens. 403 when the signed-in user does not match the claim email; 429 after too many attempts (per user, 10 minute window).

Authentication: the dashboard mm_session cookie.

Request body

Content type: application/json.

Response

200 Claimed (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/auth/claim" \
  -H "Cookie: mm_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "user_code": "string"
}'

{
  "agent_id": "string",
  "registration_id": "string",
  "registration_type": "anonymous",
  "status": "claimed",
  "name": "Production",
  "client": "string",
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
  "inbox_id": "agent@machinemail.dev",
  "email": "agent@machinemail.dev",
  "issuer": "string",
  "agent_platform": "string",
  "created_at": "2026-10-01T12:00:00.000Z",
  "claimed_at": "2026-10-01T12:00:00.000Z",
  "revoked_at": "2026-10-01T12:00:00.000Z",
  "expires_at": "2026-10-01T12:00:00.000Z",
  "inbox": {
    "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
    "inbox_id": "agent@machinemail.dev",
    "email": "agent@machinemail.dev",
    "display_name": "Support Agent",
    "client_id": "my-client-id",
    "status": "active",
    "metadata": {
      "key": "value"
    },
    "updated_at": "2026-10-01T12:00:00.000Z",
    "created_at": "2026-10-01T12:00:00.000Z",
    "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
    "ephemeral": false,
    "ttl_seconds": 1,
    "expires_at": "2026-10-01T12:00:00.000Z",
    "created_by": "api"
  }
}

Sign-in Options

GET /auth/config

How people sign in to this server: email codes (POST /auth/email/start), social providers (GET /auth/social/{provider}) and SSO, all on MachineMail’s own pages; on a server without them (self-hosted or development), magic links (POST /auth/magic-link).

Authentication: None.

Response

200 Sign-in options (application/json)

Errors

Example

curl "https://api.machinemail.dev/auth/config"

{
  "workos": false,
  "email_code": false,
  "providers": ["google"],
  "magic_link": false,
  "password": false,
  "authkit": false
}

Send Sign-in Code

POST /auth/email/start

Starts an email-code sign-in: emails a 6-digit code, valid 10 minutes, and sets the mm_signin cookie that POST /auth/email/verify needs. Sending it again sends a new code. The answer is the same whether or not the address has an account; a malformed address is 400, and an unknown or used invitation_token is 404.

SSO discovery first: when the address’s domain is verified by an organization with an active SSO connection, no code is sent and redirect_to is that connection.

With an invitation_token and no email, the code goes to the invited address; signing in accepts the invitation.

dev_code (the code itself) only in development with the noop transport, or with MACHINEMAIL_DEV_MAGIC_LINK=true; never otherwise in production.

429 also while email codes for the address are paused for this client IP (too many wrong codes from it; see POST /auth/email/verify), when this client IP (an IPv6 client by its /64) has had 5 new codes for the address in 15 minutes, and when the address has had 10 new codes in the last hour from any IP, counting verification codes. These limits are kept in the database (every machine) and only hold back new codes: a code already sent can still be used.

404 when this server does not offer email-code sign-in (GET /auth/config).

Rate limited per client IP and per email address (5 codes per 15 minutes per address and client IP; 10 per hour per address): 429 with Retry-After.

A request whose Origin is another site is refused (403).

Authentication: None.

Request body

Content type: application/json.

Response

202 Code sent (if the address can receive mail), or the SSO redirect (application/json)

Headers:

Errors

Example

curl -X POST "https://api.machinemail.dev/auth/email/start" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "agent@machinemail.dev"
}'

{
  "ok": true,
  "redirect_to": "string",
  "dev_code": "string"
}

Verify Sign-in Code

POST /auth/email/verify

Checks the emailed code for the sign-in in the mm_signin cookie. Signed in: sets mm_session and redirect_to is next. The sign-in may need another step first (signed_in: false, redirect_to is our organization picker, the email verification screen or SSO).

A wrong code is 400 (param code); after 5 wrong codes, or when the code has expired or was already used, there is no sign-in any more: 404, send a new code. An invitation revoked, expired or accepted since the code was sent is 404 too. Other failures answer redirect_to: /login?error=<code>.

20 wrong codes for one address from one client IP (an IPv6 client by its /64) within 24 hours (counted in the database, across codes and machines) pause email codes for that address from that IP: this endpoint and POST /auth/email/start answer 429 to it until the oldest is a day old, and the address is emailed. Other IPs are not affected, so guessing cannot lock the person out of their right code.

Rate limited per client IP and per email address (5 attempts, then 1 per minute, per address and client IP): 429 with Retry-After.

A request whose Origin is another site is refused (403).

Authentication: None.

Request body

Content type: application/json.

Response

200 Signed in, or the next step (application/json)

Headers:

Errors

Example

curl -X POST "https://api.machinemail.dev/auth/email/verify" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "string"
}'

{
  "ok": true,
  "signed_in": false,
  "redirect_to": "string"
}

Get First API Key

GET /auth/first-key

The organization API key created on first sign-in, with its plaintext secret. Returned once: the record is deleted on read and expires 10 minutes after sign-in; 404 afterwards.

Authentication: the dashboard mm_session cookie.

Response

200 The key, shown once (application/json)

api_key is a OneTimeApiKey:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/auth/first-key" \
  -H "Cookie: mm_session=$SESSION"

{
  "api_key": {
    "api_key_id": "key_01k6x3e8mr0000h4r0ty6c9k1n",
    "api_key": "mm_live_4f8Kq2ZbX9mN3pR7tV1wY6cH0jL5sD8a",
    "prefix": "mm_live_4f8K",
    "name": "Production",
    "created_at": "2026-10-01T12:00:00.000Z"
  }
}

Preview Invitation

GET /auth/invitations/{token}

What an invitation link (/invite/{token}) is for: the organization, the invited address (masked) and the state. Accept it by signing in with invitation_token (POST /auth/email/start or GET /auth/social/{provider}). 404 for an unknown token, or when this server does not use invitation links. 429 with Retry-After when the lookup is rate limited, or cannot be answered right now (an outage): retry after that many seconds.

Authentication: None.

Path parameters

Response

200 The invitation (application/json)

Errors

Example

curl "https://api.machinemail.dev/auth/invitations/string"

{
  "organization_name": "string",
  "email": "agent@machinemail.dev",
  "state": "pending",
  "expires_at": "2026-10-01T12:00:00.000Z"
}

Log In (Deprecated)

POST /auth/login

Deprecated: the dashboard signs in with POST /auth/magic-link. Sets the mm_session cookie.

Off in production unless the server sets MACHINEMAIL_PASSWORD_AUTH=true: 404 otherwise.

Rate limited per client IP and per email address (5 attempts, then 1 per minute; a successful sign-in resets the address): 429 with Retry-After.

Authentication: None.

Request body

Content type: application/json.

Response

200 Signed in (application/json)

Headers:

user is a User:

organization is a Organization:

Errors

Example

curl -X POST "https://api.machinemail.dev/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "agent@machinemail.dev",
  "password": "string"
}'

{
  "user": {
    "user_id": "usr_01k6x3j0rw0000n8w4yc0g3q5s",
    "email": "agent@machinemail.dev",
    "name": "Production",
    "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
    "role": "owner",
    "created_at": "2026-10-01T12:00:00.000Z"
  },
  "organization": {
    "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
    "name": "Production",
    "slug": "string",
    "plan": "free",
    "inbox_count": 1,
    "domain_count": 1,
    "usage": {
      "message_count": 1,
      "storage_bytes": 2048,
      "messages_received_30d": 1,
      "messages_sent_30d": 1
    },
    "shared_domain": "string",
    "updated_at": "2026-10-01T12:00:00.000Z",
    "created_at": "2026-10-01T12:00:00.000Z"
  }
}

Log Out

POST /auth/logout

Ends the session in the mm_session cookie, if any, and clears the cookie. Succeeds without a session too.

Authentication: None.

Response

200 Signed out (application/json)

Errors

Example

curl -X POST "https://api.machinemail.dev/auth/logout"

{
  "ok": true
}

Redeem Magic Link

GET /auth/magic

The link in the sign-in email. Consumes the token (single use), sets the mm_session cookie and redirects to next (default /app). On a first sign-in it creates the user, an organization, a Default Pod and a first organization API key, and adds welcome=1 to the redirect; fetch that key once with GET /auth/first-key.

Authentication: None.

Query parameters

Response

302 Signed in: Location is next and Set-Cookie carries mm_session. Otherwise Location is /login?error=expired.

Headers:

Errors

Example

curl "https://api.machinemail.dev/auth/magic"

Request Magic Link

POST /auth/magic-link

Emails a single-use sign-in link (<PUBLIC_URL>/auth/magic?token=..., valid 15 minutes). Always 202 {"ok": true} for a well-formed email, whether or not it has an account; a malformed address is 400.

Development only (noop transport, or MACHINEMAIL_DEV_MAGIC_LINK=true): the body also carries dev_link.

Off (404) when email-code sign-in is on (sign in with an email code instead), unless the server sets MACHINEMAIL_MAGIC_LINK=true.

Rate limited per client IP and per email address (5 links per 15 minutes per address): 429 with Retry-After.

Authentication: None.

Request body

Content type: application/json.

Response

202 Accepted. The link was sent if the address can receive mail. (application/json)

Errors

Example

curl -X POST "https://api.machinemail.dev/auth/magic-link" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "agent@machinemail.dev"
}'

{
  "ok": true,
  "dev_link": "string"
}

Current User

GET /auth/me

The signed-in user and the organization the session is on; user.role is their role there. For what an API key can see, use GET /v0/auth/me.

Authentication: the dashboard mm_session cookie.

Response

200 The session (application/json)

user is a User:

organization is a Organization:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/auth/me" \
  -H "Cookie: mm_session=$SESSION"

{
  "user": {
    "user_id": "usr_01k6x3j0rw0000n8w4yc0g3q5s",
    "email": "agent@machinemail.dev",
    "name": "Production",
    "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
    "role": "owner",
    "created_at": "2026-10-01T12:00:00.000Z"
  },
  "organization": {
    "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
    "name": "Production",
    "slug": "string",
    "plan": "free",
    "inbox_count": 1,
    "domain_count": 1,
    "usage": {
      "message_count": 1,
      "storage_bytes": 2048,
      "messages_received_30d": 1,
      "messages_sent_30d": 1
    },
    "shared_domain": "string",
    "updated_at": "2026-10-01T12:00:00.000Z",
    "created_at": "2026-10-01T12:00:00.000Z"
  }
}

Preview App Authorization

GET /auth/oauth/authorize

Called by the dashboard /connect page for a signed-in person. Returns the client (its name and logo are self-reported unless it identified itself with a metadata document URL), where the response goes, the resource and the requested scopes. 404 for an unknown, decided or expired request. Dashboard session only: API keys are not accepted.

Authentication: the dashboard mm_session cookie.

Query parameters

Response

200 The pending request (application/json)

client is a OAuthClientInfo:

Each item of scopes is a ScopeDescription:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/auth/oauth/authorize?request_id=string" \
  -H "Cookie: mm_session=$SESSION"

{
  "request_id": "string",
  "client": {
    "client_id": "my-client-id",
    "client_name": "string",
    "client_uri": "https://example.com",
    "logo_uri": "https://example.com",
    "registration": "dynamic",
    "host": "string"
  },
  "redirect_uri": "https://example.com",
  "redirect_host": "string",
  "redirect_loopback": false,
  "resource": "string",
  "scopes": [
    {
      "scope": "inboxes.read",
      "description": "string"
    }
  ],
  "created_at": "2026-10-01T12:00:00.000Z",
  "expires_at": "2026-10-01T12:00:00.000Z"
}

Approve App Authorization

POST /auth/oauth/authorize/approve

Approves a pending request for the signed-in person’s organization, optionally limited to one pod or one inbox, and returns redirect_to (the client’s redirect_uri with code, state and iss) for the browser to follow. The app then appears under Connected apps (/v0/oauth-grants). Dashboard session only.

Authentication: the dashboard mm_session cookie.

Request body

Content type: application/json.

Response

200 Approved (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/auth/oauth/authorize/approve" \
  -H "Cookie: mm_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "request_id": "string"
}'

{
  "status": "approved",
  "redirect_to": "string"
}

Deny App Authorization

POST /auth/oauth/authorize/deny

Denies a pending request and returns redirect_to (the client’s redirect_uri with error=access_denied, state and iss). Dashboard session only.

Authentication: the dashboard mm_session cookie.

Request body

Content type: application/json.

Response

200 Denied (application/json)

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/auth/oauth/authorize/deny" \
  -H "Cookie: mm_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "request_id": "string"
}'

{
  "status": "approved",
  "redirect_to": "string"
}

List My Organizations

GET /auth/organizations

Every organization the signed-in person belongs to, with their role, for the organization switcher.

Authentication: the dashboard mm_session cookie.

Response

200 Organizations (application/json)

Each item of organizations is a MembershipOrganization:

Errors

Error bodies use the error envelope.

Example

curl "https://api.machinemail.dev/auth/organizations" \
  -H "Cookie: mm_session=$SESSION"

{
  "organizations": [
    {
      "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
      "name": "Production",
      "slug": "string",
      "role": "owner",
      "current": false
    }
  ]
}

Create Organization

POST /auth/organizations

Creates an organization (with its Default Pod) owned by the signed-in person, and switches the session to it.

Authentication: the dashboard mm_session cookie.

Request body

Content type: application/json.

Response

201 Created; the session is on the new organization (application/json)

user is a User:

organization is a Organization:

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/auth/organizations" \
  -H "Cookie: mm_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Production"
}'

{
  "user": {
    "user_id": "usr_01k6x3j0rw0000n8w4yc0g3q5s",
    "email": "agent@machinemail.dev",
    "name": "Production",
    "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
    "role": "owner",
    "created_at": "2026-10-01T12:00:00.000Z"
  },
  "organization": {
    "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
    "name": "Production",
    "slug": "string",
    "plan": "free",
    "inbox_count": 1,
    "domain_count": 1,
    "usage": {
      "message_count": 1,
      "storage_bytes": 2048,
      "messages_received_30d": 1,
      "messages_sent_30d": 1
    },
    "shared_domain": "string",
    "updated_at": "2026-10-01T12:00:00.000Z",
    "created_at": "2026-10-01T12:00:00.000Z"
  }
}

Switch Organization

POST /auth/organizations/switch

Moves the session to another organization the person belongs to. 404 when they do not belong to it. An organization other than the one the session signed in to must allow how the session signed in, under its own sign-in policy: 403 when it does not (for example the organization requires single sign-on and the session signed in with an email code); sign in again to that organization.

Authentication: the dashboard mm_session cookie.

Request body

Content type: application/json.

Response

200 The session, on the organization (application/json)

user is a User:

organization is a Organization:

Errors

Error bodies use the error envelope.

Example

curl -X POST "https://api.machinemail.dev/auth/organizations/switch" \
  -H "Cookie: mm_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e"
}'

{
  "user": {
    "user_id": "usr_01k6x3j0rw0000n8w4yc0g3q5s",
    "email": "agent@machinemail.dev",
    "name": "Production",
    "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
    "role": "owner",
    "created_at": "2026-10-01T12:00:00.000Z"
  },
  "organization": {
    "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
    "name": "Production",
    "slug": "string",
    "plan": "free",
    "inbox_count": 1,
    "domain_count": 1,
    "usage": {
      "message_count": 1,
      "storage_bytes": 2048,
      "messages_received_30d": 1,
      "messages_sent_30d": 1
    },
    "shared_domain": "string",
    "updated_at": "2026-10-01T12:00:00.000Z",
    "created_at": "2026-10-01T12:00:00.000Z"
  }
}

Get Sign-in in Progress

GET /auth/pending

The sign-in in progress in this browser (mm_signin cookie), for the code, organization picker and email verification screens. 404 when there is none or it expired.

Authentication: None.

Response

200 The sign-in in progress (application/json)

Errors

Example

curl "https://api.machinemail.dev/auth/pending"

{
  "step": "code",
  "email": "agent@machinemail.dev",
  "organizations": [
    {
      "id": "string",
      "name": "Production"
    }
  ],
  "invitation": false
}

Choose Organization

POST /auth/pending/organization

Finishes a sign-in that needs an organization picked (organization_selection_required) with one of the organizations offered (GET /auth/pending); any other ID is 400.

A request whose Origin is another site is refused (403).

Authentication: None.

Request body

Content type: application/json.

Response

200 Signed in, or the next step (application/json)

Headers:

Errors

Example

curl -X POST "https://api.machinemail.dev/auth/pending/organization" \
  -H "Content-Type: application/json" \
  -d '{
  "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e"
}'

{
  "ok": true,
  "signed_in": false,
  "redirect_to": "string"
}

Verify Email

POST /auth/pending/verify

Finishes a sign-in that needs the email verified (email_verification_required, for example a GitHub account whose email GitHub does not vouch for) with the code emailed to that address. Wrong codes as for POST /auth/email/verify. Each such sign-in is a new code for the address, counted with email codes (POST /auth/email/start): past those limits the callback goes to /login?error=codes_paused and no code is sent.

Rate limited per client IP and per email address (5 attempts, then 1 per minute, per address and client IP): 429 with Retry-After.

A request whose Origin is another site is refused (403).

Authentication: None.

Request body

Content type: application/json.

Response

200 Signed in, or the next step (application/json)

Headers:

Errors

Example

curl -X POST "https://api.machinemail.dev/auth/pending/verify" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "string"
}'

{
  "ok": true,
  "signed_in": false,
  "redirect_to": "string"
}

Sign Up (Deprecated)

POST /auth/signup

Deprecated: the dashboard signs in with POST /auth/magic-link. Creates a user, an organization, a Default Pod and a first organization API key (returned once as api_key), and sets the mm_session cookie.

It does not verify the email address, so it is off in production unless the server sets MACHINEMAIL_PASSWORD_AUTH=true: 404 otherwise.

A taken address and a password shorter than 8 characters both answer 409 with the same message.

Rate limited per client IP and per email address (5 attempts, then 1 per minute): 429 with Retry-After.

Authentication: None.

Request body

Content type: application/json.

Response

201 Signed up and signed in (application/json)

Headers:

user is a User:

organization is a Organization:

api_key is a OneTimeApiKey:

Errors

Example

curl -X POST "https://api.machinemail.dev/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "agent@machinemail.dev",
  "password": "string",
  "name": "Production"
}'

{
  "user": {
    "user_id": "usr_01k6x3j0rw0000n8w4yc0g3q5s",
    "email": "agent@machinemail.dev",
    "name": "Production",
    "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
    "role": "owner",
    "created_at": "2026-10-01T12:00:00.000Z"
  },
  "organization": {
    "organization_id": "org_01k6x2m9qd0000a7h3kq9v2c4e",
    "name": "Production",
    "slug": "string",
    "plan": "free",
    "inbox_count": 1,
    "domain_count": 1,
    "usage": {
      "message_count": 1,
      "storage_bytes": 2048,
      "messages_received_30d": 1,
      "messages_sent_30d": 1
    },
    "shared_domain": "string",
    "updated_at": "2026-10-01T12:00:00.000Z",
    "created_at": "2026-10-01T12:00:00.000Z"
  },
  "api_key": {
    "api_key_id": "key_01k6x3e8mr0000h4r0ty6c9k1n",
    "api_key": "mm_live_4f8Kq2ZbX9mN3pR7tV1wY6cH0jL5sD8a",
    "prefix": "mm_live_4f8K",
    "name": "Production",
    "created_at": "2026-10-01T12:00:00.000Z"
  }
}

Sign In with a Social Provider

GET /auth/social/{provider}

Sends the browser straight to Google, GitHub, Apple or Microsoft (no page in between), with a single-use state bound to this browser by a short-lived cookie (mm_oauth_state, Path=/auth/callback). The provider returns to GET /auth/callback.

404 when this server does not offer social sign-in or that provider (GET /auth/config lists them).

Authentication: None.

Path parameters

Query parameters

Response

302 To the provider.

Headers:

Errors

Example

curl "https://api.machinemail.dev/auth/social/google"