Lockally Admin API
Tenant-admin login (email+password → session token for app.lockally.com)
Tenant-admin login (email+password → session token for app.lockally.com)
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/lockally-com:lockally-com-admin-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: lockally control plane Admin API
version: 0.1.0
summary: REST API for managing tenants, domains, mailboxes, and outbound mail
description: 'The lockally control plane lets integrators and direct customers manage
everything except actual mail data flow (which uses standard JMAP / IMAP /
SMTP-submission against the data plane endpoints).
**Authentication.** All `/v1/*` endpoints require a Bearer API key in the
`Authorization` header. Keys are formatted `lk_live__`,
or `lk_test_` for a test key. Create keys in the dashboard, or with
`POST /v1/api-keys` using a key that holds `tenant:admin`.
The key''s plan is checked on every request, so a key stops working if the
account moves to a plan without API access, and works again if it moves back.
**Errors.** Failures return RFC 9457
`application/problem+json` documents.
**Scopes.** Each endpoint requires a specific scope on the presented key.
Insufficient scope returns `403` with the required scope name in `detail`.'
contact:
name: lockally support
email: support@lockally.com
license:
name: AGPL-3.0-only OR LicenseRef-LOC-Commercial
identifier: AGPL-3.0-only
servers:
- url: https://api.lockally.com
description: Production
- url: http://127.0.0.1:8081
description: Local development / spike
security:
- bearerAuth: []
tags:
- name: Admin
description: Tenant-admin login (email+password → session token for app.lockally.com)
paths:
/v1/admin/login:
post:
operationId: adminLogin
tags:
- Admin
summary: Tenant-admin email+password login
description: 'Exchanges an admin''s email + password for a session token. The web
console at `app.lockally.com` posts this on form submission and
stores the returned token in an httpOnly cookie.
**No enumeration leak.** Wrong-email and wrong-password both return
the same 401 with title "Invalid credentials". The argon2id verify
runs even on lookup miss (well, structurally, the lookup fails fast
but the response shape is constant) so timing leaks are bounded.
Tokens are prefixed `adm_sess_` and valid for 7 days. Use as the
`Authorization: Bearer` value on all subsequent calls.'
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
- password
properties:
email:
type: string
format: email
password:
type: string
format: password
minLength: 8
responses:
'200':
description: Authenticated.
content:
application/json:
schema:
type: object
required:
- token
- expires_at
- admin
- tenant
properties:
token:
type: string
example: adm_sess_...
expires_at:
type: string
format: date-time
admin:
$ref: '#/components/schemas/Admin'
tenant:
$ref: '#/components/schemas/Tenant'
'400':
$ref: '#/components/responses/ProblemBadRequest'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
/v1/admin/logout:
post:
operationId: adminLogout
tags:
- Admin
summary: Invalidate the current admin session
description: 'Deletes the session row from the database. Idempotent, calling
logout on an already-invalid token returns 204 anyway.'
responses:
'204':
description: Logged out.
'400':
$ref: '#/components/responses/ProblemBadRequest'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
/v1/admin/me:
get:
operationId: getCurrentAdmin
tags:
- Admin
summary: Get the current admin + tenant
description: 'Returns the admin profile + tenant for the session token presented
in `Authorization: Bearer`. Used by the web console''s layout load
function to populate the sidebar.
Returns 403 if called with an API key (lk_live_*) bearer, admin
context only exists for session tokens.'
responses:
'200':
description: Admin + tenant.
content:
application/json:
schema:
type: object
required:
- admin
- tenant
properties:
admin:
$ref: '#/components/schemas/Admin'
tenant:
$ref: '#/components/schemas/Tenant'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
components:
responses:
ProblemForbidden:
description: API key lacks the required scope.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
ProblemBadRequest:
description: Malformed request.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
ProblemUnauthorized:
description: Missing, malformed, or invalid API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
schemas:
Tenant:
type: object
required:
- id
- slug
- display_name
- status
- plan
- rate_cap_per_min
- daily_msg_quota
- admin_email
- created_at
properties:
id:
type: string
format: uuid
slug:
type: string
example: workgrid
display_name:
type: string
example: WorkGrid
status:
type: string
enum:
- active
- suspended
- closing
- closed
plan:
type: string
example: starter
rate_cap_per_min:
type: integer
description: Per-tenant share of the per-VPS 5/min outbound cap (L6).
example: 1
daily_msg_quota:
type: integer
example: 1000
admin_email:
type: string
format: email
created_at:
type: string
format: date-time
suspended_at:
type: string
format: date-time
nullable: true
closed_at:
type: string
format: date-time
nullable: true
hard_delete_after:
type: string
format: date-time
nullable: true
Admin:
type: object
required:
- id
- tenant_id
- email
- role
- created_at
properties:
id:
type: string
format: uuid
tenant_id:
type: string
format: uuid
email:
type: string
format: email
display_name:
type: string
role:
type: string
enum:
- admin
- viewer
last_login_at:
type: string
format: date-time
nullable: true
created_at:
type: string
format: date-time
Problem:
description: RFC 9457 problem-details document.
type: object
required:
- type
- status
- title
properties:
type:
type: string
format: uri
default: about:blank
status:
type: integer
title:
type: string
detail:
type: string
instance:
type: string
format: uri
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: lk_live_<prefix>_<secret>
description: API key, format `lk_live_<8-char-prefix>_<32-char-secret>`.
oauth2:
type: oauth2
description: 'OAuth 2.1 (authorization code + PKCE). The access token is sent as the
`Authorization: Bearer` credential, exactly like an API key, so any SDK
that accepts a bearer token works with OAuth. Discovery:
`/.well-known/oauth-authorization-server`.
'
flows:
authorizationCode:
authorizationUrl: https://api.lockally.com/oauth/authorize
tokenUrl: https://api.lockally.com/oauth/token
scopes:
inboxes:read: Read agent-accessible mailboxes and threads
inboxes:write: Send and act on agent-accessible mailboxes