API auth

This page is for the person who connects a program to the API.

Authentication protocol endpoints. Better Auth implements them; the contract records their shapes so the generated client owns every call.

getAuthSession

GET /api/auth/get-session

Report the current session.

Reports the session that the request cookie names, or null when there is none.

Authentication

No security scheme is declared. See the operation description.

Responses

200

The current session, or null.

JSON

{
  "description": "The current session, or null.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AuthCurrentSession"
      }
    }
  }
}

Schemas: AuthCurrentSession.

400

The request did not match the endpoint.

JSON

{
  "description": "The request did not match the endpoint.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

401

The credential was refused.

JSON

{
  "description": "The credential was refused.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

403

The request did not come from the configured origin.

JSON

{
  "description": "The request did not come from the configured origin.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

404

The named record does not exist.

JSON

{
  "description": "The named record does not exist.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

429

Too many attempts. Try again later.

JSON

{
  "description": "Too many attempts. Try again later.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

requestPasswordReset

POST /api/auth/request-password-reset

Ask for a password reset message.

Sends a reset link to the address when a mail transport is configured. The link opens the reset page of the application. A deployment without one uses the operator recovery command instead. The answer never says whether the address exists, and the messages to one address count against its mail budget.

Authentication

No security scheme is declared. See the operation description.

Request body

JSON

{
  "description": "The address that asks for a reset message.",
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AuthPasswordResetRequest"
      }
    }
  }
}

Schemas: AuthPasswordResetRequest.

Responses

200

The request was accepted.

JSON

{
  "description": "The request was accepted.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AuthOutcome"
      }
    }
  }
}

Schemas: AuthOutcome.

400

The request did not match the endpoint.

JSON

{
  "description": "The request did not match the endpoint.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

401

The credential was refused.

JSON

{
  "description": "The credential was refused.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

403

The request did not come from the configured origin.

JSON

{
  "description": "The request did not come from the configured origin.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

404

The named record does not exist.

JSON

{
  "description": "The named record does not exist.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

413

The request body is larger than the configured limit.

JSON

{
  "description": "The request body is larger than the configured limit.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

415

The request media type is not supported.

JSON

{
  "description": "The request media type is not supported.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

429

Too many attempts. Try again later.

JSON

{
  "description": "Too many attempts. Try again later.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

resetPassword

POST /api/auth/reset-password

Choose a new password with a reset token.

Sets a new password and revokes every session of the account. The token works once and expires one hour after it was created.

Authentication

No security scheme is declared. See the operation description.

Request body

JSON

{
  "description": "The new password and the reset token.",
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AuthPasswordReset"
      }
    }
  }
}

Schemas: AuthPasswordReset.

Responses

200

The password was replaced.

JSON

{
  "description": "The password was replaced.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AuthOutcome"
      }
    }
  }
}

Schemas: AuthOutcome.

400

The request did not match the endpoint.

JSON

{
  "description": "The request did not match the endpoint.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

401

The credential was refused.

JSON

{
  "description": "The credential was refused.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

403

The request did not come from the configured origin.

JSON

{
  "description": "The request did not come from the configured origin.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

404

The named record does not exist.

JSON

{
  "description": "The named record does not exist.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

413

The request body is larger than the configured limit.

JSON

{
  "description": "The request body is larger than the configured limit.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

415

The request media type is not supported.

JSON

{
  "description": "The request media type is not supported.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

429

Too many attempts. Try again later.

JSON

{
  "description": "Too many attempts. Try again later.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

signInWithPassword

POST /api/auth/sign-in/email

Checks a local password and sets the Secure HttpOnly session cookie. Public registration is disabled, so this endpoint never creates an account.

Authentication

No security scheme is declared. See the operation description.

Request body

JSON

{
  "description": "Address and password of a local account.",
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AuthPasswordSignIn"
      }
    }
  }
}

Schemas: AuthPasswordSignIn.

Responses

200

The sign-in completed.

JSON

{
  "description": "The sign-in completed.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AuthSession"
      }
    }
  }
}

Schemas: AuthSession.

400

The request did not match the endpoint.

JSON

{
  "description": "The request did not match the endpoint.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

401

The credential was refused.

JSON

{
  "description": "The credential was refused.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

403

The request did not come from the configured origin.

JSON

{
  "description": "The request did not come from the configured origin.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

404

The named record does not exist.

JSON

{
  "description": "The named record does not exist.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

413

The request body is larger than the configured limit.

JSON

{
  "description": "The request body is larger than the configured limit.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

415

The request media type is not supported.

JSON

{
  "description": "The request media type is not supported.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

429

Too many attempts. Try again later.

JSON

{
  "description": "Too many attempts. Try again later.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

signOut

POST /api/auth/sign-out

End the current session.

Removes the session on the server and clears the session cookie. A cleared session cannot be used again.

Authentication

No security scheme is declared. See the operation description.

Request body

JSON

{
  "description": "Sign-out carries no data.",
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AuthSignOut"
      }
    }
  }
}

Schemas: AuthSignOut.

Responses

200

The session ended.

JSON

{
  "description": "The session ended.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AuthSignOutResult"
      }
    }
  }
}

Schemas: AuthSignOutResult.

400

The request did not match the endpoint.

JSON

{
  "description": "The request did not match the endpoint.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

401

The credential was refused.

JSON

{
  "description": "The credential was refused.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

403

The request did not come from the configured origin.

JSON

{
  "description": "The request did not come from the configured origin.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

404

The named record does not exist.

JSON

{
  "description": "The named record does not exist.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

413

The request body is larger than the configured limit.

JSON

{
  "description": "The request body is larger than the configured limit.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

415

The request media type is not supported.

JSON

{
  "description": "The request media type is not supported.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

429

Too many attempts. Try again later.

JSON

{
  "description": "Too many attempts. Try again later.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

registerAccount

POST /api/registrations

Make an account from an invitation and sign it in.

Makes an account for the address that the invitation binds, with the given password, and starts its session. A used, revoked, or expired invitation makes nothing, and the answer does not say which of the three applied. Two requests with one invitation make one account. When the installation names its terms and its privacy notice, the request names the versions that the person accepted, and a missing or an older version makes nothing (record 0120).

Authentication

No security scheme is declared. See the operation description.

Request body

JSON

{
  "description": "The invitation token and the password of the new account.",
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/RegistrationInput"
      }
    }
  }
}

Schemas: RegistrationInput.

Responses

201

The account exists and its session started.

JSON

{
  "description": "The account exists and its session started.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/Registered"
      }
    }
  }
}

Schemas: Registered.

400

The request did not match the contract.

JSON

{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

403

The invitation opens nothing. The code is invitation_invalid for a token that expired, that somebody used, that an administrator revoked, or that never existed. The answer does not say which.

JSON

{
  "description": "The invitation opens nothing. The code is invitation_invalid for a token that expired, that somebody used, that an administrator revoked, or that never existed. The answer does not say which.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

409

The change cannot be accepted next to the state that the workspace holds. The code names the reason: path_conflict for a path that another live file occupies, and mutation_reused for a mutation identity that was already used for another operation. A save of a note adds epoch_mismatch, which means that the note holds another generation of its document, so the device reads the current document before it saves again.

JSON

{
  "description": "The change cannot be accepted next to the state that the workspace holds. The code names the reason: path_conflict for a path that another live file occupies, and mutation_reused for a mutation identity that was already used for another operation. A save of a note adds epoch_mismatch, which means that the note holds another generation of its document, so the device reads the current document before it saves again.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

413

The request body is larger than the configured limit. A save of a note adds document_too_large, which means that the update or the document it would produce passes a bound of the workspace. The work stays on the device, which offers recovery rather than sending the same bytes again.

JSON

{
  "description": "The request body is larger than the configured limit. A save of a note adds document_too_large, which means that the update or the document it would produce passes a bound of the workspace. The work stays on the device, which offers recovery rather than sending the same bytes again.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

415

The request media type is not supported.

JSON

{
  "description": "The request media type is not supported.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

429

Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.

JSON

{
  "description": "Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.",
  "headers": {
    "retry-after": {
      "description": "The seconds after which the caller may try again.",
      "schema": {
        "type": "string",
        "maxLength": 16
      }
    },
    "notesapp-limit": {
      "description": "The limit of the month that refused the request, on the codes download_limit and storage_busy only, so the answer of a HEAD request names it too (record 0193).",
      "schema": {
        "$ref": "#/components/schemas/UsageLimit"
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails, UsageLimit.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

getSignUpChallenge

GET /api/registrations/challenge

Read a proof of work challenge for one sign-up.

Answers a random value, a difficulty and an expiry, signed by this server (record 0115). The browser finds a solution whose digest starts with as many zero bits as the difficulty names, and sends it with the sign-up. One solution makes one account. No third party takes part. The installation must have the open registration policy.

Authentication

No security scheme is declared. See the operation description.

Responses

200

One challenge for the proof of work of a sign-up.

JSON

{
  "description": "One challenge for the proof of work of a sign-up.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/SignUpChallenge"
      }
    }
  }
}

Schemas: SignUpChallenge.

400

The request did not match the contract.

JSON

{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

403

The actor may not perform this operation.

JSON

{
  "description": "The actor may not perform this operation.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

429

JSON

{
  "description": "Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.",
  "headers": {
    "retry-after": {
      "description": "The seconds after which the caller may try again.",
      "schema": {
        "type": "string",
        "maxLength": 16
      }
    },
    "notesapp-limit": {
      "description": "The limit of the month that refused the request, on the codes download_limit and storage_busy only, so the answer of a HEAD request names it too (record 0193).",
      "schema": {
        "$ref": "#/components/schemas/UsageLimit"
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails, UsageLimit.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

readInvitation

POST /api/registrations/invitation

Read the address that a valid invitation binds.

Answers the address of a valid invitation, so the person sees the address of their new account before they choose a password. The token travels in the body, so it reaches no address log.

Authentication

No security scheme is declared. See the operation description.

Request body

JSON

{
  "description": "The token of the invitation to read.",
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/InvitationReadInput"
      }
    }
  }
}

Schemas: InvitationReadInput.

Responses

200

The address that the invitation binds.

JSON

{
  "description": "The address that the invitation binds.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/InvitationAddress"
      }
    }
  }
}

Schemas: InvitationAddress.

400

The request did not match the contract.

JSON

{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

403

The invitation opens nothing. The code is invitation_invalid for a token that expired, that somebody used, that an administrator revoked, or that never existed. The answer does not say which.

JSON

{
  "description": "The invitation opens nothing. The code is invitation_invalid for a token that expired, that somebody used, that an administrator revoked, or that never existed. The answer does not say which.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

413

JSON

{
  "description": "The request body is larger than the configured limit. A save of a note adds document_too_large, which means that the update or the document it would produce passes a bound of the workspace. The work stays on the device, which offers recovery rather than sending the same bytes again.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

415

The request media type is not supported.

JSON

{
  "description": "The request media type is not supported.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

429

JSON

{
  "description": "Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.",
  "headers": {
    "retry-after": {
      "description": "The seconds after which the caller may try again.",
      "schema": {
        "type": "string",
        "maxLength": 16
      }
    },
    "notesapp-limit": {
      "description": "The limit of the month that refused the request, on the codes download_limit and storage_busy only, so the answer of a HEAD request names it too (record 0193).",
      "schema": {
        "$ref": "#/components/schemas/UsageLimit"
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails, UsageLimit.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

signUpAccount

POST /api/registrations/open

Ask for an account with an address and a password.

Open registration (record 0114). A new address gets a pending account and a verification link by mail. An address that already signs in gets a mail that tells its owner about the attempt. A pending address is replaced, with its password. Every one of these answers the same status and body, so the answer states nothing about the address. The installation must have the open registration policy.

Authentication

No security scheme is declared. See the operation description.

Request body

JSON

{
  "description": "The address and the password of the account that a person asks for.",
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/SignUpInput"
      }
    }
  }
}

Schemas: SignUpInput.

Responses

202

The sign-up was taken. A message goes to the address.

JSON

{
  "description": "The sign-up was taken. A message goes to the address.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/SignUpAccepted"
      }
    }
  }
}

Schemas: SignUpAccepted.

400

The request did not match the contract.

JSON

{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

403

The actor may not perform this operation.

JSON

{
  "description": "The actor may not perform this operation.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

409

JSON

{
  "description": "The change cannot be accepted next to the state that the workspace holds. The code names the reason: path_conflict for a path that another live file occupies, and mutation_reused for a mutation identity that was already used for another operation. A save of a note adds epoch_mismatch, which means that the note holds another generation of its document, so the device reads the current document before it saves again.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

413

JSON

{
  "description": "The request body is larger than the configured limit. A save of a note adds document_too_large, which means that the update or the document it would produce passes a bound of the workspace. The work stays on the device, which offers recovery rather than sending the same bytes again.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

415

The request media type is not supported.

JSON

{
  "description": "The request media type is not supported.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

429

JSON

{
  "description": "Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.",
  "headers": {
    "retry-after": {
      "description": "The seconds after which the caller may try again.",
      "schema": {
        "type": "string",
        "maxLength": 16
      }
    },
    "notesapp-limit": {
      "description": "The limit of the month that refused the request, on the codes download_limit and storage_busy only, so the answer of a HEAD request names it too (record 0193).",
      "schema": {
        "$ref": "#/components/schemas/UsageLimit"
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails, UsageLimit.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

verifyAddress

POST /api/registrations/verification

Prove the address of a pending account and make the account.

Takes the token of a verification link. A valid token marks the address verified and makes the account, and the person then signs in. An expired, a replaced and an unknown token all take one refusal. The token travels in the body, so it reaches no address log.

Authentication

No security scheme is declared. See the operation description.

Request body

JSON

{
  "description": "The token of a verification link.",
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AddressVerificationInput"
      }
    }
  }
}

Schemas: AddressVerificationInput.

Responses

200

The address is proved and the account exists.

JSON

{
  "description": "The address is proved and the account exists.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AddressVerified"
      }
    }
  }
}

Schemas: AddressVerified.

400

The request did not match the contract.

JSON

{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

403

The verification link opens nothing. The code is verification_invalid for a token that expired, that a later sign-up replaced, or that never existed. The answer does not say which. The code is registration_closed when the installation stopped open registration after the sign-up.

JSON

{
  "description": "The verification link opens nothing. The code is verification_invalid for a token that expired, that a later sign-up replaced, or that never existed. The answer does not say which. The code is registration_closed when the installation stopped open registration after the sign-up.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

413

JSON

{
  "description": "The request body is larger than the configured limit. A save of a note adds document_too_large, which means that the update or the document it would produce passes a bound of the workspace. The work stays on the device, which offers recovery rather than sending the same bytes again.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

415

The request media type is not supported.

JSON

{
  "description": "The request media type is not supported.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

429

JSON

{
  "description": "Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.",
  "headers": {
    "retry-after": {
      "description": "The seconds after which the caller may try again.",
      "schema": {
        "type": "string",
        "maxLength": 16
      }
    },
    "notesapp-limit": {
      "description": "The limit of the month that refused the request, on the codes download_limit and storage_busy only, so the answer of a HEAD request names it too (record 0193).",
      "schema": {
        "$ref": "#/components/schemas/UsageLimit"
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails, UsageLimit.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

getSetupStatus

GET /api/setup

Report whether the first account exists and who can make one.

Reports if first-run setup is complete without exposing account data.

Authentication

No security scheme is declared. See the operation description.

Responses

200

The setup state.

JSON

{
  "description": "The setup state.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "initialized",
          "openRegistration",
          "passwordReset",
          "legalDocuments"
        ],
        "properties": {
          "initialized": {
            "type": "boolean",
            "readOnly": true
          },
          "openRegistration": {
            "type": "boolean",
            "readOnly": true,
            "description": "Whether a person can ask for an account without an invitation (record 0114)."
          },
          "passwordReset": {
            "type": "boolean",
            "readOnly": true,
            "description": "Whether a person can reset a forgotten password by mail (record 0141). It is false when the installation has no mail transport."
          },
          "legalDocuments": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/LegalDocuments"
              },
              {
                "type": "null"
              }
            ],
            "description": "The terms and the privacy notice, or null when the installation names none (record 0120)."
          }
        }
      }
    }
  }
}

Schemas: LegalDocuments.

400

The request did not match the contract.

JSON

{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

429

JSON

{
  "description": "Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.",
  "headers": {
    "retry-after": {
      "description": "The seconds after which the caller may try again.",
      "schema": {
        "type": "string",
        "maxLength": 16
      }
    },
    "notesapp-limit": {
      "description": "The limit of the month that refused the request, on the codes download_limit and storage_busy only, so the answer of a HEAD request names it too (record 0193).",
      "schema": {
        "$ref": "#/components/schemas/UsageLimit"
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails, UsageLimit.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

createOwner

POST /api/setup

Create the first account during first-run setup.

Creates the first account of the installation as its administrator and signs it in. This operation is refused after the first account exists. Every later account comes in through an invitation.

Authentication

No security scheme is declared. See the operation description.

Request body

JSON

{
  "description": "The email address and password of the first account.",
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "email",
          "password"
        ],
        "properties": {
          "email": {
            "$ref": "#/components/schemas/EmailAddress"
          },
          "password": {
            "$ref": "#/components/schemas/Password"
          }
        }
      }
    }
  }
}

Schemas: EmailAddress, Password.

Responses

201

The first account was created and signed in.

JSON

{
  "description": "The first account was created and signed in.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "initialized"
        ],
        "properties": {
          "initialized": {
            "type": "boolean",
            "readOnly": true
          }
        }
      }
    }
  }
}

400

The request did not match the contract.

JSON

{
  "description": "The request did not match the contract.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

403

The actor may not perform this operation.

JSON

{
  "description": "The actor may not perform this operation.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

413

JSON

{
  "description": "The request body is larger than the configured limit. A save of a note adds document_too_large, which means that the update or the document it would produce passes a bound of the workspace. The work stays on the device, which offers recovery rather than sending the same bytes again.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

415

The request media type is not supported.

JSON

{
  "description": "The request media type is not supported.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.

429

JSON

{
  "description": "Too many requests. Too many attempts were made in a short time, the account runs its limit of archive jobs, or the account or the installation downloaded the most bytes or read the most objects that one calendar month in UTC allows (record 0193). The code names the cause: rate_limited, archive_job_running or download_limit. Nothing changed.",
  "headers": {
    "retry-after": {
      "description": "The seconds after which the caller may try again.",
      "schema": {
        "type": "string",
        "maxLength": 16
      }
    },
    "notesapp-limit": {
      "description": "The limit of the month that refused the request, on the codes download_limit and storage_busy only, so the answer of a HEAD request names it too (record 0193).",
      "schema": {
        "$ref": "#/components/schemas/UsageLimit"
      }
    }
  },
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails, UsageLimit.

500

The service failed to complete the request.

JSON

{
  "description": "The service failed to complete the request.",
  "content": {
    "application/problem+json": {
      "schema": {
        "$ref": "#/components/schemas/ProblemDetails"
      }
    }
  }
}

Schemas: ProblemDetails.