---
title: "Authenticate and retrieve API keys"
method: POST
path: "/v1/auth/login"
tags: ["Auth"]
---

# Authenticate and retrieve API keys

`POST /v1/auth/login`

## Request

- Base URL: `https://api.honkio.ca`
- URL: `https://api.honkio.ca/v1/auth/login`
- Auth: none required

Validates email and password hash. Returns account info and API key prefix list for the dashboard session.

## Request body

- object
  - `email` string, email, required
  - `password` string, required

## Response `200`

Signed in. The two session keys are shown once; the dashboard uses them for its own calls.

- object: Signed in. The two session keys are shown once; the dashboard uses them for its own calls.
  - `account` object, required
    - `id` string, required
    - `name` string, required
    - `email` string, required
    - `status` 'PENDING_PAYMENT' | 'ACTIVE', required
    - `balance_cents` integer, required
    - `created_at` string, date-time, required
  - `api_keys` ApiKey[], required: The account's active USER keys, without permissions or defaultDeny.
    - `id` string, required
    - `keyPrefix` string, required: Non-secret prefix for display and identification.
    - `mode` 'LIVE' | 'TEST', required
    - `label` string, nullable, required
    - `createdAt` string, date-time, required
    - `lastUsedAt` string, date-time, nullable, required
    - `defaultDeny` boolean: Present on GET /v1/accounts/me and /v1/accounts/{id}; absent from the login response.
    - `permissions` ApiKeyPermissions: Per-resource permissions. Each key is a resource name; value is a string of allowed operation letters: r=read, w=write/create, m=modify/update, d=delete. A missing key denies all access to that resource.
    - `email_domain_ids` string[], nullable: The email domains this key may send from (ids from /v1/email-domains): null when unrestricted, [] when restricted to none (its domains were deleted). Present on GET /v1/accounts/me and /v1/accounts/{id}; absent from the login response.
    - `oauth_grant` boolean: True when an OAuth connection holds this key: it can be revoked but not rotated (409 CONFLICT, details.reason "oauth_grant"). Present on GET /v1/accounts/me and /v1/accounts/{id}; absent from the login response.
  - `session_key` string, required: A LIVE dashboard session key, valid for 7 days or until the next login or password change.
  - `session_key_id` string, required
  - `session_test_key` string, required: The matching TEST dashboard session key.
  - `session_test_key_id` string, required

## Other responses

- `401`: INVALID_CREDENTIALS: unknown email or wrong password.
- `403`: ACCOUNT_SUSPENDED: the account is suspended or closed.
- `422`: VALIDATION_ERROR: the request failed validation; details names the fields.
- `429`: RATE_LIMITED: 10 attempts per 15 minutes from one address, or 20 failures per 15 minutes for one email.

---

[API](https://skmtc.dev/honkio/apis/honkio-api.md) · [All operations](https://skmtc.dev/honkio/apis/honkio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/honkio/apis/honkio-api/revisions/ce4ed3fe9691?raw)