Log in with email and password
const url = 'https://api.aetherpush.com/v1/auth/login';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"email":"adrian@aetherpush.com","password":"correct horse battery staple"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.aetherpush.com/v1/auth/login \ --header 'Content-Type: application/json' \ --data '{ "email": "adrian@aetherpush.com", "password": "correct horse battery staple" }'Authenticates an account and returns an access key (session bearer
token) usable on subsequent requests. The returned accessKey is
the raw token — store it securely; the server cannot return it
again.
Rate limited to 5 failed attempts per client address per 15 minutes. The address is the exact one on IPv4 and the /64 prefix on IPv6.
Repeated failures against a single account escalate rather than lock
it: past a small number of recent failures the next attempt must
carry a Turnstile token in challengeToken, and the server signals
that with a 403 carrying code: challenge_required. Where that
escalation is not enabled, the account instead stops accepting
attempts for an hour after ten recent failures.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Cloudflare Turnstile token. Only needed once an account has
accumulated enough recent failed logins for the server to ask
for one, which it signals with a 403 carrying
code: challenge_required. Sending it before then is harmless
and ignored.
Example
{ "email": "adrian@aetherpush.com", "password": "correct horse battery staple"}Responses
Section titled “Responses”Password accepted. For accounts without MFA the response carries
the access key. For MFA-enabled accounts it instead carries a
short-lived pending login token; complete the login via
/v1/auth/mfa/verify (passkey), /v1/auth/mfa/totp
(authenticator code), or /v1/auth/mfa/recovery (recovery
code). methods lists which of those this account can use. The
two shapes are told apart by the mfaRequired field.
object
Raw bearer token. Send as Authorization: Bearer <accessKey>
on subsequent requests. Store securely (cookie or secure
storage). The server cannot reveal it again.
Unix timestamp in milliseconds at which this token expires.
Present and true when the account has no MFA method yet. Every
account is expected to enroll a passkey or an authenticator app.
The dashboard nags until mfaSetupDeadline and blocks
navigation after it. Clients that cannot enroll (the CLI) may
ignore this field.
Unix timestamp in milliseconds. Present alongside
mfaSetupRequired; fixed on the account’s first MFA-less login
and stable on later logins. Before it, MFA setup is a
dismissible prompt; after it, the dashboard requires setup
before continuing.
Returned by /v1/auth/login when the account has MFA enabled. The
password was verified, but no access key is issued until a passkey
assertion, an authenticator code, or a recovery code is presented
together with the pending login token. The token is single use, allows five verification
attempts, and expires after five minutes.
object
Short-lived opaque token identifying this login attempt.
Unix timestamp in milliseconds at which the pending login expires.
MFA methods this account can complete the login with.
Examples
{ "accessKey": "abc123-base64url-secret", "expires": 1719964800000}{ "mfaRequired": true, "pendingToken": "pend123-base64url-secret", "expires": 1719961200000, "methods": [ "passkey", "totp", "recovery_code" ]}Email or password missing.
object
Human-readable error message.
Unique identifier for the request, also exposed as the X-Request-Id response header.
Example
{ "error": "Email and password are required.", "requestId": "req_abc123"}Invalid email or password.
object
Human-readable error message.
Unique identifier for the request, also exposed as the X-Request-Id response header.
Example
{ "error": "Invalid email or password.", "requestId": "req_abc123"}Either the email address has not been verified, or the account
needs a Turnstile token before the attempt is considered. The two
are told apart by the code field, which is present only on the
second.
object
Human-readable error message.
Unique identifier for the request, also exposed as the X-Request-Id response header.
Returned with HTTP 403 when the account has enough recent failed
logins that the next attempt must carry a Turnstile token. Retry the
same credentials with challengeToken set.
object
Examples
{ "error": "Please verify your email address before logging in.", "requestId": "req_abc123"}{ "error": "Please complete the verification challenge to continue.", "code": "challenge_required", "requestId": "req_abc123"}Too many login attempts.
Returned with HTTP 429 when an endpoint-specific rate limit is hit.
retryAfterSeconds indicates how long the client should wait
before retrying.
object
Example
{ "error": "Too many login attempts. Please try again later.", "retryAfterSeconds": 900, "requestId": "req_abc123"}Internal server error.
object
Human-readable error message.
Unique identifier for the request, also exposed as the X-Request-Id response header.
Example
{ "error": "The requested resource was not found.", "requestId": "req_abc123"}