API v1
v1
View as Markdown

Log in

POST /api/v1/login no token

Exchange an address and a password for a token. The token is named after device_name, so you can tell your integrations apart later and revoke one without touching the rest.

A user who has turned on two factor authentication must send a valid code as well, from their authenticator app or from their recovery codes. No token is issued until it passes, because an endpoint that skipped it would be a way around the second factor rather than another way in.

Wrong password, suspended account, an account that signs in through an external provider, and an address nobody holds all answer the same way. Anything else would tell somebody which addresses have accounts here.

Body parameters

Sent as JSON. Anything not listed here is ignored.

email string Required

The address the account signs in with.

password string Required

The password of the account.

code string Optional

A code from the authenticator app, or one of the recovery codes. Required when the user has two factor authentication turned on. A recovery code is spent the moment it works.

device_name string Optional

What the token is for, in a few words. Shown in security settings.

Returns

A token, in plain text, or a 401 status when anything at all was wrong with the credentials.

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/login \
-X POST \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"password": "a-very-strong-password",
"device_name": "Dundie awards bot"
}'
const response = await fetch('https://my.monicahq.com/api/v1/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
password: 'a-very-strong-password',
device_name: 'Dundie awards bot',
}),
})
const data = await response.json()
$response = Http::post('https://my.monicahq.com/api/v1/login', [
'email' => '[email protected]',
'password' => 'a-very-strong-password',
'device_name' => 'Dundie awards bot',
]);
Response 200
{
"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.