Lockally Users API

End-user (mailbox user) lifecycle

GitHub OpenAPI

Operations 5

GET /v1/users List users #
POST /v1/users Create a user #
GET /v1/users/{id} Get a user #
PATCH /v1/users/{id} Update a user #
DELETE /v1/users/{id} Deprovision a user #

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-users-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-users-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: lockally control plane Users 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: Users
  description: End-user (mailbox user) lifecycle
paths:
  /v1/users:
    get:
      tags:
      - Users
      summary: List users
      operationId: listUsers
      x-required-scope: tenant:admin
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
      responses:
        '200':
          description: User list.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - limit
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  limit:
                    type: integer
        '401':
          $ref: '#/components/responses/ProblemUnauthorized'
        '403':
          $ref: '#/components/responses/ProblemForbidden'
    post:
      tags:
      - Users
      summary: Create a user
      operationId: createUser
      x-required-scope: tenant:admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - first_name
              - last_name
              properties:
                email:
                  type: string
                  format: email
                first_name:
                  type: string
                last_name:
                  type: string
                title:
                  type: string
                department:
                  type: string
      responses:
        '201':
          description: User created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/ProblemBadRequest'
        '401':
          $ref: '#/components/responses/ProblemUnauthorized'
        '403':
          $ref: '#/components/responses/ProblemForbidden'
        '409':
          description: Duplicate email address.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /v1/users/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Users
      summary: Get a user
      operationId: getUser
      x-required-scope: tenant:admin
      responses:
        '200':
          description: User info.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/ProblemUnauthorized'
        '403':
          $ref: '#/components/responses/ProblemForbidden'
        '404':
          $ref: '#/components/responses/ProblemNotFound'
    patch:
      tags:
      - Users
      summary: Update a user
      description: 'Setting `status` to `suspended` or `deprovisioned` takes away everything

        the person signs in with: each of their mailboxes and their console

        membership is disabled, app passwords are revoked, and every webmail and

        console session ends. Setting it back to `active` restores what the

        suspension disabled, and nothing an admin disabled for another reason.

        API keys belong to the workspace, not to the person who created them,

        and are not revoked; rotate any the person had access to.'
      operationId: updateUser
      x-required-scope: tenant:admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                last_name:
                  type: string
                title:
                  type: string
                department:
                  type: string
                status:
                  type: string
                  enum:
                  - active
                  - suspended
                  - deprovisioned
      responses:
        '200':
          description: Updated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/ProblemBadRequest'
        '401':
          $ref: '#/components/responses/ProblemUnauthorized'
        '403':
          $ref: '#/components/responses/ProblemForbidden'
        '404':
          $ref: '#/components/responses/ProblemNotFound'
        '409':
          description: The person is the caller, or the workspace's last active admin.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    delete:
      tags:
      - Users
      summary: Deprovision a user
      description: 'Sets the user''s status to `deprovisioned` and ends their access: each

        of their mailboxes and their console membership is disabled, app

        passwords are revoked, and every webmail and console session ends. Their

        mail is kept. API keys belong to the workspace and are not revoked;

        rotate any the person had access to.'
      operationId: deleteUser
      x-required-scope: tenant:admin
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/ProblemUnauthorized'
        '403':
          $ref: '#/components/responses/ProblemForbidden'
        '404':
          $ref: '#/components/responses/ProblemNotFound'
        '409':
          description: The person is the caller, or the workspace's last active admin.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    User:
      type: object
      required:
      - id
      - tenant_id
      - email
      - first_name
      - last_name
      - status
      - created_at
      - updated_at
      properties:
        id:
          type: string
          format: uuid
        tenant_id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        title:
          type: string
        department:
          type: string
        status:
          type: string
          enum:
          - active
          - suspended
          - deprovisioned
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        mailbox_count:
          type: integer
    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
  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'
    ProblemNotFound:
      description: Resource not found under the calling tenant.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  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