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.
| 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.
| Name | In | Type | Description |
|---|---|---|---|
If-Match (required) | header | string | The ETag of the account as last read. |
Request body, application/merge-patch+json: AccountUpdate
| 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.
| 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.
| Name | In | Type | Description |
|---|---|---|---|
If-Match (required) | header | string | The ETag of the settings as last read. |
Request body, application/json: AccountSettingsUpdate
| 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 | 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
| 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
| 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
| 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.
| 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
| 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 |