Lockally Admin API

Tenant-admin login (email+password → session token for app.lockally.com)

GitHub OpenAPI

Operations 3

POST /v1/admin/login Tenant-admin email+password login #
POST /v1/admin/logout Invalidate the current admin session #
GET /v1/admin/me Get the current admin + tenant #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/lockally-com:lockally-com-admin-api"
All apis
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.

Get an API 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 Specification

lockally-com-admin-api-openapi.yml Raw ↑
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