List email addresses

GET /api/auth/email admin

Every verified address on the deployment, paged by cursor. Unverified ones live at /api/auth/email/unverified.

Parameters

prefix string

Narrow to addresses starting with this. Query parameter.

cursor string

Continue from a previous page. Query parameter.

limit number

Page size. Query parameter.

Returns

The page of addresses, and a cursor when there is more.

Request

curl "https://example.com/api/auth/email?limit=2" \
  -H "authorization: Bearer $TOKEN"

Response

{
  "addresses": ["ada@example.com", "grace@example.com"],
  "cursor": null
}

Look up the identity behind an address

GET /api/auth/email/:address open

Resolves an address to the identity that registered it. 404 when nothing claims it — which is the answer a registration form is checking for.

Parameters

address string Required

Path parameter, URL-encoded.

Returns

{ identity }, or 404.

Request

curl https://example.com/api/auth/email/ada%40example.com

Response

{
  "identity": {
    "id": "01J2788XY98FDTA410C8S716CD",
    "kind": "member",
    "displayName": "Ada Lovelace"
  }
}

Check whether an address is registered

HEAD /api/auth/email/:address open

The same lookup with no body — the right call for an availability check.

Parameters

address string Required

Path parameter, URL-encoded.

Returns

200 when registered, 404 when free.

Request

curl -I https://example.com/api/auth/email/ada%40example.com

Response

{}

List unverified addresses

GET /api/auth/email/unverified session

Addresses that have been offered but not yet proven — a registration begun and not finished.

Parameters

cursor string

Continue from a previous page. Query parameter.

limit number

Page size. Query parameter.

Returns

The page of unverified addresses, and a cursor when there is more.

Request

curl https://example.com/api/auth/email/unverified \
  -H "authorization: Bearer $TOKEN"

Response

{
  "addresses": ["grace@example.com"],
  "cursor": null
}

Check the unverified listing

HEAD /api/auth/email/unverified session

The same call with no body.

Returns

200.

Request

curl -I https://example.com/api/auth/email/unverified \
  -H "authorization: Bearer $TOKEN"

Response

{}

Read an unverified address record

GET /api/auth/email/unverified/:address session

What is known about an address that has been offered but not proven — when it was seen, and what it was offered for.

Parameters

address string Required

Path parameter, URL-encoded.

Returns

{ record }. record is null when nothing has been recorded.

Request

curl https://example.com/api/auth/email/unverified/grace%40example.com \
  -H "authorization: Bearer $TOKEN"

Response

{
  "record": {
    "address": "grace@example.com",
    "challenged": 1767225600
  }
}

Check for an unverified record

HEAD /api/auth/email/unverified/:address session

The same read with no body.

Parameters

address string Required

Path parameter, URL-encoded.

Returns

200.

Request

curl -I https://example.com/api/auth/email/unverified/grace%40example.com \
  -H "authorization: Bearer $TOKEN"

Response

{}

Begin email registration

POST /api/auth/email/:address/registration/challenge open

Mails a registration challenge to the address. Answers 200 whether or not the address is already taken, so it cannot be used to find out which addresses have accounts.

Parameters

address string Required

Path parameter, URL-encoded.

kind enum

The authentication payload the challenge is for.

Possible enum values

email

method enum

How the challenge is delivered — a link or a code.

Possible enum values

verification
code

displayName string

Carried through to the account when the flow completes.

Returns

200. The challenge itself arrives by mail.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/registration/challenge \
  -H "content-type: application/json" \
  -d '{ "kind": "email", "method": "verification", "email": "ada@example.com" }'

Response

{
  "ok": true
}

Complete email registration

POST /api/auth/email/:address/registration open

Redeems the token from the challenge mail and creates the account, signed in. This is passwordless registration: the address is proven before the identity exists.

Parameters

address string Required

Path parameter, URL-encoded.

verification string Required

The token from the challenge mail.

Returns

A session — identity, identity token and refresh token — with both cookies set.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/registration \
  -H "content-type: application/json" \
  -d '{ "verification": "01J2788XY98FDTA410C8S716CE" }'

Response

{
  "identity": { "id": "01J2788XY98FDTA410C8S716CD", "kind": "member" },
  "identityToken": "eyJhbGciOi…",
  "refreshToken": "eyJhbGciOi…"
}

Begin email sign-in

POST /api/auth/email/:address/signin/challenge open

Mails a magic link or a code to the address. Answers 200 whether or not the address has an account.

Parameters

address string Required

Path parameter, URL-encoded.

kind enum

The authentication payload the challenge is for.

Possible enum values

email

method enum

How the challenge is delivered — a link or a code.

Possible enum values

verification
code

displayName string

Carried through to the account when the flow completes.

Returns

200. The challenge itself arrives by mail.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/signin/challenge \
  -H "content-type: application/json" \
  -d '{ "kind": "email", "method": "verification", "email": "ada@example.com" }'

Response

{
  "ok": true
}

Complete email sign-in

POST /api/auth/email/:address/signin open

Redeems the token from the mail and returns a session.

Parameters

address string Required

Path parameter, URL-encoded.

verification string Required

The token from the challenge mail.

Returns

A session — identity, identity token and refresh token — with both cookies set.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/signin \
  -H "content-type: application/json" \
  -d '{ "verification": "01J2788XY98FDTA410C8S716CE" }'

Response

{
  "identity": { "id": "01J2788XY98FDTA410C8S716CD", "kind": "member" },
  "identityToken": "eyJhbGciOi…",
  "refreshToken": "eyJhbGciOi…"
}

Begin email recovery

POST /api/auth/email/:address/recovery/challenge open

Mails a recovery challenge. This is the way back in for somebody who has lost their passphrase.

Parameters

address string Required

Path parameter, URL-encoded.

kind enum

The authentication payload the challenge is for.

Possible enum values

email

method enum

How the challenge is delivered — a link or a code.

Possible enum values

verification
code

displayName string

Carried through to the account when the flow completes.

Returns

200. The challenge itself arrives by mail.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/recovery/challenge \
  -H "content-type: application/json" \
  -d '{ "kind": "email", "method": "verification", "email": "ada@example.com" }'

Response

{
  "ok": true
}

Complete email recovery

POST /api/auth/email/:address/recovery open

Redeems the token and returns a session, far enough in to set a new passphrase at POST /api/auth/identity/:id/passphrase.

Parameters

address string Required

Path parameter, URL-encoded.

verification string Required

The token from the challenge mail.

Returns

A session — identity, identity token and refresh token — with both cookies set.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/recovery \
  -H "content-type: application/json" \
  -d '{ "verification": "01J2788XY98FDTA410C8S716CE" }'

Response

{
  "identity": { "id": "01J2788XY98FDTA410C8S716CD", "kind": "member" },
  "identityToken": "eyJhbGciOi…",
  "refreshToken": "eyJhbGciOi…"
}

Check an address’s verification state

GET /api/auth/email/:address/verification open

Not implemented. Answers 501.

Whether an address is verified is answerable today from the directories: HEAD /api/auth/email/:address finds a verified one, and GET /api/auth/email/unverified/:address finds one still waiting.

Parameters

address string Required

Path parameter, URL-encoded.

Returns

501.

Request

curl https://example.com/api/auth/email/ada%40example.com/verification

Response

{
  "status": 501,
  "statusText": "Not Implemented"
}

Send a verification challenge

POST /api/auth/email/:address/verification/challenge open

Not implemented. Answers 501, with the challenge result echoed back.

The working path for verifying an address on an existing account is POST /api/auth/identity/:id/email/challenge then POST /api/auth/identity/:id/email/verify. To send the mail directly, admins have POST /api/auth/email/:address/notification/verification/challenge.

Parameters

address string Required

Path parameter, URL-encoded.

Returns

501.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/verification/challenge \
  -H "content-type: application/json" \
  -d '{}'

Response

{
  "status": 501,
  "statusText": "Not Implemented"
}

Redeem a verification

POST /api/auth/email/:address/verification/verify open

Not implemented. Answers 501, with the verify result echoed back.

Use POST /api/auth/identity/:id/email/verify, which is the same act against an account that exists.

Parameters

address string Required

Path parameter, URL-encoded.

verification string

The token from the challenge mail.

Returns

501.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/verification/verify \
  -H "content-type: application/json" \
  -d '{ "verification": "01J2788XY98FDTA410C8S716CE" }'

Response

{
  "status": 501,
  "statusText": "Not Implemented"
}

Sends account mail to an address. Every route in this family takes ?preview=true, which renders the message and returns it as HTML instead of sending it — the way to see what a template produces without mailing anybody.

Send an arbitrary message

POST /api/auth/email/:address/notification admin

The open form: you supply the message. The routes below are the named notices, which build their own.

Parameters

address string Required

Path parameter, URL-encoded.

preview boolean

Render and return the HTML instead of sending. Query parameter.

subject string Required

The subject line.

text string

The plain-text body.

html string

The HTML body.

from string

Defaults to the deployment's sender.

Returns

The send result — or the rendered HTML, with ?preview=true.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/notification \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "subject": "Hello", "text": "Hello, Ada." }'

Response

{
  "sent": true,
  "id": "01J2788XY98FDTA410C8S716CE"
}

Send the registration challenge mail

POST /api/auth/email/:address/notification/registration/challenge admin

The mail that carries the link or code a new account is proven with. Takes ?preview=true to render the message as HTML instead of sending it.

Parameters

address string Required

Path parameter, URL-encoded.

preview boolean

Render and return the HTML instead of sending. Query parameter.

verification string

The token to embed in the link.

displayName string

Who to greet.

Returns

The send result — or the rendered HTML, with ?preview=true.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/notification/registration/challenge \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "verification": "01J2788XY98FDTA410C8S716CE" }'

Response

{
  "sent": true,
  "id": "01J2788XY98FDTA410C8S716CE"
}

Send the registration success mail

POST /api/auth/email/:address/notification/registration/success admin

The welcome mail, sent once an account exists. Takes ?preview=true to render the message as HTML instead of sending it.

Parameters

address string Required

Path parameter, URL-encoded.

preview boolean

Render and return the HTML instead of sending. Query parameter.

displayName string

Who to greet.

Returns

The send result — or the rendered HTML, with ?preview=true.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/notification/registration/success \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "displayName": "Ada Lovelace" }'

Response

{
  "sent": true,
  "id": "01J2788XY98FDTA410C8S716CE"
}

Send the sign-in challenge mail

POST /api/auth/email/:address/notification/signin/challenge admin

The magic link or code that signs somebody in. Takes ?preview=true to render the message as HTML instead of sending it.

Parameters

address string Required

Path parameter, URL-encoded.

preview boolean

Render and return the HTML instead of sending. Query parameter.

verification string

The token to embed in the link.

Returns

The send result — or the rendered HTML, with ?preview=true.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/notification/signin/challenge \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "verification": "01J2788XY98FDTA410C8S716CE" }'

Response

{
  "sent": true,
  "id": "01J2788XY98FDTA410C8S716CE"
}

Send the verification challenge mail

POST /api/auth/email/:address/notification/verification/challenge admin

Asks the holder of an address to prove it. Takes ?preview=true to render the message as HTML instead of sending it.

Parameters

address string Required

Path parameter, URL-encoded.

preview boolean

Render and return the HTML instead of sending. Query parameter.

verification string

The token to embed in the link.

Returns

The send result — or the rendered HTML, with ?preview=true.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/notification/verification/challenge \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "verification": "01J2788XY98FDTA410C8S716CE" }'

Response

{
  "sent": true,
  "id": "01J2788XY98FDTA410C8S716CE"
}

Send the address verified mail

POST /api/auth/email/:address/notification/verification/verified admin

Confirms an address has been proven. Takes ?preview=true to render the message as HTML instead of sending it.

Parameters

address string Required

Path parameter, URL-encoded.

preview boolean

Render and return the HTML instead of sending. Query parameter.

Returns

The send result — or the rendered HTML, with ?preview=true.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/notification/verification/verified \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{}'

Response

{
  "sent": true,
  "id": "01J2788XY98FDTA410C8S716CE"
}

Send the session created mail

POST /api/auth/email/:address/notification/session/created admin

Tells the address a new session was opened — the "new sign-in" mail. Takes ?preview=true to render the message as HTML instead of sending it.

Parameters

address string Required

Path parameter, URL-encoded.

preview boolean

Render and return the HTML instead of sending. Query parameter.

jti string

The session that was created.

agent string

The browser and platform it was opened from.

Returns

The send result — or the rendered HTML, with ?preview=true.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/notification/session/created \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "jti": "01J2788XY98FDTA410C8S716CE", "agent": "Chrome on macOS" }'

Response

{
  "sent": true,
  "id": "01J2788XY98FDTA410C8S716CE"
}

Send the session invalidated mail

POST /api/auth/email/:address/notification/session/invalidated admin

Tells the address a session was ended. Takes ?preview=true to render the message as HTML instead of sending it.

Parameters

address string Required

Path parameter, URL-encoded.

preview boolean

Render and return the HTML instead of sending. Query parameter.

jti string

The session that was ended.

Returns

The send result — or the rendered HTML, with ?preview=true.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/notification/session/invalidated \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "jti": "01J2788XY98FDTA410C8S716CE" }'

Response

{
  "sent": true,
  "id": "01J2788XY98FDTA410C8S716CE"
}

Send the suspension imposed mail

POST /api/auth/email/:address/notification/suspension/imposed admin

Tells the address its account has been suspended. Takes ?preview=true to render the message as HTML instead of sending it.

Parameters

address string Required

Path parameter, URL-encoded.

preview boolean

Render and return the HTML instead of sending. Query parameter.

reason string

What to tell them.

Returns

The send result — or the rendered HTML, with ?preview=true.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/notification/suspension/imposed \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "reason": "Unusual activity" }'

Response

{
  "sent": true,
  "id": "01J2788XY98FDTA410C8S716CE"
}

Send the suspension lifted mail

POST /api/auth/email/:address/notification/suspension/lifted admin

Tells the address its account is usable again. Takes ?preview=true to render the message as HTML instead of sending it.

Parameters

address string Required

Path parameter, URL-encoded.

preview boolean

Render and return the HTML instead of sending. Query parameter.

reason string

What to tell them.

Returns

The send result — or the rendered HTML, with ?preview=true.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/notification/suspension/lifted \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "reason": "Review complete" }'

Response

{
  "sent": true,
  "id": "01J2788XY98FDTA410C8S716CE"
}

Send the termination warning mail

POST /api/auth/email/:address/notification/termination/warning admin

Warns that the account is scheduled for deletion. Takes ?preview=true to render the message as HTML instead of sending it.

Parameters

address string Required

Path parameter, URL-encoded.

preview boolean

Render and return the HTML instead of sending. Query parameter.

reason string

What to tell them.

scheduled number

When termination runs, as a Unix timestamp.

Returns

The send result — or the rendered HTML, with ?preview=true.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/notification/termination/warning \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "reason": "Inactive for 24 months", "scheduled": 1767830400 }'

Response

{
  "sent": true,
  "id": "01J2788XY98FDTA410C8S716CE"
}

Send the termination executed mail

POST /api/auth/email/:address/notification/termination/executed admin

Tells the address its account has been deleted. Takes ?preview=true to render the message as HTML instead of sending it.

Parameters

address string Required

Path parameter, URL-encoded.

preview boolean

Render and return the HTML instead of sending. Query parameter.

reason string

What to tell them.

Returns

The send result — or the rendered HTML, with ?preview=true.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/notification/termination/executed \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "reason": "Requested by the account holder" }'

Response

{
  "sent": true,
  "id": "01J2788XY98FDTA410C8S716CE"
}

Send the address unassigned mail

POST /api/auth/email/:address/notification/unassigned admin

Tells an address it is no longer attached to an account — sent to the old address after a change, so a takeover is visible to the person who lost it. Takes ?preview=true to render the message as HTML instead of sending it.

Parameters

address string Required

Path parameter, URL-encoded.

preview boolean

Render and return the HTML instead of sending. Query parameter.

Returns

The send result — or the rendered HTML, with ?preview=true.

Request

curl -X POST https://example.com/api/auth/email/ada%40example.com/notification/unassigned \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{}'

Response

{
  "sent": true,
  "id": "01J2788XY98FDTA410C8S716CE"
}

Challenge, then complete

Sending mail directly

Not implemented

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns