Skip to content

API reference: account

The signed-in account: its profile and storage use, its handle and email address, email verification, tips by email, password change, and deletion. Profile changes are JSON Merge Patches held to the ETag last read. Also CampaignLark’s webhook, which ends a consent to tips by email.

GET /v1/account

Returns the caller's account profile, with the validator a patch is held to. Needs a session.

Responses
Status Description Body
200

Account profile.

Account application/json
401

No valid session token

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

PATCH /v1/account

Patches the handle, the email address, discovery by email, or tips by email. Needs a session.

A JSON Merge Patch against the account as last read. A new address waits in pendingEmail until verified, so no address is ever answered as taken.

Parameters
Name In Type Description
If-Match (required) header string

The ETag of the account as last read.

Request body, application/merge-patch+json: AccountUpdate

Responses
Status Description Body
200

Updated profile.

Account application/json
400

The request is malformed

Problem application/problem+json
401

No valid session token

Problem application/problem+json
409

Handle already taken

Problem application/problem+json
412

The resource changed since the ETag in If-Match was read

Problem application/problem+json
413

The body is too large

Problem application/problem+json
415

The body is not a JSON Merge Patch

Problem application/problem+json
428

The write must state If-Match

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

GET /v1/account/settings

Returns the account's sealed settings and their `ETag`. Needs a session.

The settings the account’s devices sealed under the account key, which the server never opens. An account that never wrote any has no sealed, at version 0, and an ETag to write the first against.

Responses
Status Description Body
200

The sealed settings.

AccountSettings application/json
401

No valid session token

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

PUT /v1/account/settings

Replaces the account's sealed settings, the first ones included. Needs a session.

A whole replacement, written against the settings last read: the server cannot merge ciphertext. The account’s other devices hear that the account moved.

Parameters
Name In Type Description
If-Match (required) header string

The ETag of the settings as last read.

Request body, application/json: AccountSettingsUpdate

Responses
Status Description Body
200

The settings as stored.

AccountSettings application/json
400

The request is malformed

Problem application/problem+json
401

No valid session token

Problem application/problem+json
412

The settings changed since they were read

Problem application/problem+json
413

Larger than an account’s settings may be

Problem application/problem+json
415

The body is not JSON

Problem application/problem+json
428

Sent without If-Match

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

POST /v1/account/tips/webhook

Receives the webhooks of tips by email, signature-verified; only those that end a consent act. Needs no session.

An unsubscribe, a spam complaint or a hard bounce withdraws the consent the contact’s account gave before the event, so a replay never withdraws a later one. Every other event is answered and ignored.

Request body, application/json: object

Responses
Status Description Body
204

Event received

400

Invalid signature

Problem application/problem+json
413

The body is too large

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

Tips by email unavailable

Problem application/problem+json

POST /v1/account:changePassword

Changes the password: a new auth key and a rewrapped master key. Needs a session.

The KDF salt is left as is, so the recovery credential keeps working.

Request body, application/json: PasswordChange

Responses
Status Description Body
204

Password changed, other sessions revoked

400

The request is malformed

Problem application/problem+json
401

Current credential rejected

Problem application/problem+json
413

The body is too large

Problem application/problem+json
415

The body is not JSON

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

POST /v1/account:delete

Deletes the account after re-verifying the caller. Needs a session.

The database’s erasure also queues the Stripe customer’s deletion in the same commit.

Request body, application/json: AccountDelete

Responses
Status Description Body
204

Account deleted

400

The request is malformed

Problem application/problem+json
401

Credential rejected

Problem application/problem+json
413

The body is too large

Problem application/problem+json
415

The body is not JSON

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

POST /v1/account:sendVerification

Issues an email verification token for the pending address, else the current one. Needs a session.

An account is sent one a minute and five a day, counted in the database. A pending address another account holds is sent a notice instead, with no token: the answer is the same.

Responses
Status Description Body
202

Verification token issued

400

No email on the account

Problem application/problem+json
401

No valid session token

Problem application/problem+json
429

Verification emails used

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json

POST /v1/account:verifyEmail

Confirms an email address with the delivered token. Needs no session.

A pending one becomes the account’s.

Open to anyone: holding the token is what proves control of the address.

Request body, application/json: EmailVerify

Responses
Status Description Body
204

Email verified

400

Invalid or expired token

Problem application/problem+json
409

Another account took the address meanwhile

Problem application/problem+json
413

The body is too large

Problem application/problem+json
415

The body is not JSON

Problem application/problem+json
429

Too many requests

Problem application/problem+json
500

The service failed

Problem application/problem+json
503

The service is at capacity

Problem application/problem+json