API v1
v1
View as Markdown

Register

POST /api/v1/register no token

Open an account from outside the browser, and get a token for it.

The account this builds is the account the sign up screen builds, down to the first vault and the lists it starts with. The terms are asked for here too, because a second way in that skipped them would be a way around them.

An instance can stop accepting new accounts. While it does, this endpoint answers 404 whatever the body holds, before anything is validated, exactly as the sign up screen does.

The one exception is somebody an administrator admitted from the waiting list. Their email holds a link ending in a token, and sending that token as admission opens the account while new accounts are refused. The account then takes the admitted address whatever email holds, that address is already verified, and the token stops working. A token that is unknown, used, replaced or expired is ignored while the instance accepts new accounts, and answers 404 while it does not.

Body parameters

Sent as JSON. Anything not listed here is ignored.

first_name string Required

The first name of the person opening the account. Maximum 255 characters.

last_name string Required

The last name of the person opening the account. Maximum 255 characters.

email string Required

The address to sign in with, stored in lowercase. Held by nobody else, and not from a throwaway provider.

password string Required

At least 8 characters. Only a hash of it is ever written down.

password_confirmation string Required

The password again, exactly as above.

admission string Optional

The token at the end of the link an administrator sent from the waiting list, 64 characters. Only needed while the instance refuses new accounts.

terms boolean Required

Agreement with the terms of use and the privacy policy. An account cannot be opened without it.

timezone string Optional

An IANA time zone, which every date is then rendered in. Defaults to UTC.

device_name string Optional

What the token is for, in a few words. It names the key in security settings, so each integration can be revoked on its own.

Returns

A token, in plain text. This is the only time it exists in that form: only a hash of it is kept, so a token you fail to copy has to be made again.

token string

The bearer token. Send it as an Authorization header reading Bearer followed by this value, on every other endpoint. This is the only time it exists in readable form: only a hash of it is kept, so a token you fail to copy has to be made again.

expires_at timestamp

When the token stops working, as a count of seconds, or null when it never does. Every token issued today is null: expiry is not something this API sets yet, and a token is ended by revoking it.

Rate limit

Six requests per minute, per address. Every answer carries the budget left in X-RateLimit-Remaining.

POST
curl https://my.monicahq.com/api/v1/register \
-X POST \
-H "Content-Type: application/json" \
-d '{
"first_name": "Michael",
"last_name": "Scott",
"email": "[email protected]",
"password": "a-very-strong-password",
"password_confirmation": "a-very-strong-password",
"admission": "aaaabbbbccccddddeeeeffffgggghhhhiiiijjjjkkkkllllmmmmnnnnoooopppp",
"terms": true,
"device_name": "Dundie awards bot"
}'
const response = await fetch('https://my.monicahq.com/api/v1/register', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
first_name: 'Michael',
last_name: 'Scott',
password: 'a-very-strong-password',
password_confirmation: 'a-very-strong-password',
admission: 'aaaabbbbccccddddeeeeffffgggghhhhiiiijjjjkkkkllllmmmmnnnnoooopppp',
terms: true,
device_name: 'Dundie awards bot',
}),
})
const data = await response.json()
$response = Http::post('https://my.monicahq.com/api/v1/register', [
'first_name' => 'Michael',
'last_name' => 'Scott',
'email' => '[email protected]',
'password' => 'a-very-strong-password',
'password_confirmation' => 'a-very-strong-password',
'admission' => 'aaaabbbbccccddddeeeeffffgggghhhhiiiijjjjkkkkllllmmmmnnnnoooopppp',
'terms' => true,
'device_name' => 'Dundie awards bot',
]);
Response 201
{
"token": "1|f9aB2cD3eF4gH5iJ6kL7mN8oP9qR0sT1uV2w",
"expires_at": null
}

Keys act as you, with exactly the access you have. Make one per integration so you can revoke it alone.