Lockally API Keys API

API key lifecycle

GitHub OpenAPI

Operations 5

GET /v1/api-keys List API keys #
POST /v1/api-keys Create an API key #
PATCH /v1/api-keys/{id} Update an API key #
DELETE /v1/api-keys/{id} Revoke an API key #
POST /v1/api-keys/{id}/rotate Rotate an API key #

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-api-keys-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-api-keys-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: lockally control plane API Keys 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: API Keys
  description: API key lifecycle
paths:
  /v1/api-keys:
    get:
      operationId: listApiKeys
      tags:
      - API Keys
      summary: List API keys
      description: 'Returns all API keys (active and revoked) belonging to the calling

        tenant. The `secret` is **never** returned, only prefix + metadata.'
      x-required-scope: tenant:admin
      parameters:
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - label
          - created_at
          - last_used_at
          - expires_at
          default: created_at
        description: Field to order by. This list holds tens of rows per account, so every column is offered and none needs an index.
      - name: order
        in: query
        schema:
          type: string
          enum:
          - asc
          - desc
        description: Defaults to desc for the default field and asc for any other. Always tie-broken on id, so the order is total.
      responses:
        '200':
          description: Key list
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/APIKey'
        '401':
          $ref: '#/components/responses/ProblemUnauthorized'
        '403':
          $ref: '#/components/responses/ProblemForbidden'
    post:
      operationId: createApiKey
      tags:
      - API Keys
      summary: Create an API key
      description: 'Provisions a fresh API key for the calling tenant.


        **The full `secret` is included in this response ONLY**, store it

        immediately. The cleartext secret is not recoverable from the

        argon2id hash kept server-side; rotate by creating a new key and

        revoking the old one.'
      x-required-scope: tenant:admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - label
              - scopes
              properties:
                label:
                  type: string
                  description: Free-text identifier shown in the dashboard.
                  example: ci-pipeline
                scopes:
                  type: array
                  description: Allowed scopes on this key.
                  minItems: 1
                  items:
                    type: string
                    enum:
                    - tenant:read
                    - tenant:admin
                    - mailboxes:read
                    - mailboxes:write
                    - directory:sync
                    - inboxes:read
                    - inboxes:write
                    - send:read
                    - send:write
                    - templates:read
                    - templates:write
                    - suppressions:read
                    - suppressions:write
                    - webhooks:read
                    - webhooks:write
                    - domains:read
                    - domains:write
                    - migrations:read
                    - migrations:write
                test:
                  type: boolean
                  default: false
                  description: 'Issue a test key (`lk_test_` prefix). A test key accepts sends,

                    records them and fires a simulated delivery webhook without

                    sending mail, and counts against no limit or allowance.

                    '
                expires_at:
                  type: string
                  format: date-time
                  description: 'Optional. When the key stops authenticating. Omit it for a

                    key that does not expire. Must be in the future: an expiry

                    already past would mint a key that fails its first request.

                    '
      responses:
        '201':
          description: Key created, `secret` is in the response and shown only here.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIKey'
                - type: object
                  required:
                  - secret
                  properties:
                    secret:
                      type: string
                      description: The full `lk_live_<prefix>_<secret>` token. Shown ONCE.
                      example: lk_live_fbl73bhj_sfvqy7y757cnvu33bgqdpyrrhq3tyyf3
        '400':
          $ref: '#/components/responses/ProblemBadRequest'
        '401':
          $ref: '#/components/responses/ProblemUnauthorized'
        '403':
          $ref: '#/components/responses/ProblemForbidden'
  /v1/api-keys/{id}:
    patch:
      operationId: updateApiKey
      tags:
      - API Keys
      summary: Update an API key
      description: 'Changes a key''s label, scopes or expiry in place, without reissuing the

        secret.


        **Every field is optional and absent means unchanged.** Renaming a key

        does not clear its expiry. For `expires_at` there are three distinct

        requests: omit the field to leave the expiry alone, send a timestamp to

        set one, and send an explicit `null` to remove one.


        Scopes are replaced wholesale, not merged. This endpoint does not

        restrict which scopes you may grant, because `POST /v1/api-keys` never

        has either: a key with `tenant:admin` can already mint a key with any

        scope, so `tenant:admin` is root-equivalent for key management.


        A revoked key cannot be updated.'
      x-required-scope: tenant:admin
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  type: string
                  description: Free-text identifier shown in the dashboard.
                scopes:
                  type: array
                  minItems: 1
                  items:
                    type: string
                  description: Replaces the key's scopes entirely.
                expires_at:
                  type: string
                  format: date-time
                  nullable: true
                  description: A future timestamp to set an expiry, or null to remove one.
      responses:
        '200':
          description: The updated key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIKey'
        '400':
          $ref: '#/components/responses/ProblemBadRequest'
        '401':
          $ref: '#/components/responses/ProblemUnauthorized'
        '403':
          $ref: '#/components/responses/ProblemForbidden'
        '404':
          $ref: '#/components/responses/ProblemNotFound'
        '409':
          description: The key is revoked and cannot be changed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    delete:
      operationId: revokeApiKey
      tags:
      - API Keys
      summary: Revoke an API key
      description: 'Soft-deletes (sets `revoked_at`) on the named key. The row stays for

        audit purposes; the key no longer authenticates.


        You **cannot revoke the key currently being used** to make this

        call, that would lock you out. Use a different `tenant:admin` key.'
      x-required-scope: tenant:admin
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Revoked.
        '401':
          $ref: '#/components/responses/ProblemUnauthorized'
        '403':
          $ref: '#/components/responses/ProblemForbidden'
        '404':
          $ref: '#/components/responses/ProblemNotFound'
        '409':
          description: Refused, key is the one in use for this request.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
  /v1/api-keys/{id}/rotate:
    post:
      operationId: rotateApiKey
      tags:
      - API Keys
      summary: Rotate an API key
      description: 'Issues a successor key and puts a short expiry on this one, so **both

        work until the overlap ends**. That window is the point: without it,

        rotation is revocation with extra steps and every caller has to swap

        credentials in the same instant.


        The successor inherits this key''s scopes, its label (the label names

        the integration, and the integration has not changed) and its test

        flag. Its full `secret` is in this response and nowhere else.


        The response''s `expires_at` is the **predecessor''s** deadline, so you

        can see from the rotation itself how long you have to cut over.


        A key that has already been rotated cannot be rotated again: chaining

        overlaps would leave several live keys for one integration, which is

        the opposite of the intent. Rotate the successor instead.'
      x-required-scope: tenant:admin
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                grace_seconds:
                  type: integer
                  minimum: 0
                  maximum: 2592000
                  default: 86400
                  description: 'How long the old key keeps working. Defaults to 24 hours,

                    which is long enough to cut over without a scramble.

                    Capped at 30 days, because beyond that "rotated" stops

                    meaning anything.

                    '
      responses:
        '201':
          description: The successor key. Its `secret` is shown only here; `expires_at` is the predecessor's deadline.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/APIKey'
                - type: object
                  required:
                  - secret
                  properties:
                    secret:
                      type: string
                      description: The full token for the SUCCESSOR key. Shown ONCE.
        '400':
          $ref: '#/components/responses/ProblemBadRequest'
        '401':
          $ref: '#/components/responses/ProblemUnauthorized'
        '403':
          $ref: '#/components/responses/ProblemForbidden'
        '404':
          $ref: '#/components/responses/ProblemNotFound'
        '409':
          description: The key is revoked, or was already rotated.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
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'
    ProblemNotFound:
      description: Resource not found under the calling tenant.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  schemas:
    APIKey:
      type: object
      required:
      - id
      - tenant_id
      - prefix
      - scopes
      - label
      - created_at
      properties:
        id:
          type: string
          format: uuid
        tenant_id:
          type: string
          format: uuid
        prefix:
          type: string
          description: 8-char public prefix; safe to store and display.
          example: fbl73bhj
        scopes:
          type: array
          items:
            type: string
        label:
          type: string
          example: ci-pipeline
        last_used_at:
          type: string
          format: date-time
          nullable: true
        revoked_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        test:
          type: boolean
          description: 'True for an lk_test_* key: the whole request path runs but a send never reaches the mail server and nothing counts against the account.'
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: 'When the key stops authenticating. Null means it does not expire,

            which is how every key behaved before expiry existed. Enforced at

            authentication, so the key fails the first request after this

            moment rather than whenever a sweep runs.

            '
        rotated_to:
          type: string
          format: uuid
          nullable: true
          description: 'The successor issued by `POST /v1/api-keys/{id}/rotate`. Set on the

            PREDECESSOR, so you can see which key replaced this one while both

            still work through the overlap window.

            '
    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