Lockally Directory API
Global address list (GAL), directory permissions, stats
Global address list (GAL), directory permissions, stats
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-directory-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 Directory 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: Directory
description: Global address list (GAL), directory permissions, stats
paths:
/v1/gal-settings:
get:
tags:
- Directory
operationId: getGALSettings
x-required-scope: mailboxes:read
summary: Get Global Address List settings
responses:
'200':
description: GAL settings
content:
application/json:
schema:
$ref: '#/components/schemas/GALSettings'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
patch:
tags:
- Directory
operationId: updateGALSettings
x-required-scope: mailboxes:write
summary: Update GAL settings
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
gal_enabled:
type: boolean
hide_from_directory:
type: boolean
department_grouping:
type: boolean
search_visibility:
type: string
enum:
- all_users
- same_department
- admins_only
include_external_contacts:
type: boolean
responses:
'200':
description: GAL settings updated
content:
application/json:
schema:
$ref: '#/components/schemas/GALSettings'
'400':
$ref: '#/components/responses/ProblemBadRequest'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
/v1/gal-settings/rebuild-index:
post:
tags:
- Directory
operationId: rebuildGALIndex
x-required-scope: mailboxes:write
summary: Rebuild the GAL search index
responses:
'200':
description: GAL settings after index rebuild
content:
application/json:
schema:
$ref: '#/components/schemas/GALSettings'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
/v1/gal-settings/sync:
post:
tags:
- Directory
operationId: syncGAL
x-required-scope: mailboxes:write
summary: Sync GAL with external directory sources
responses:
'200':
description: GAL settings after sync
content:
application/json:
schema:
$ref: '#/components/schemas/GALSettings'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
/v1/directory-permissions:
get:
tags:
- Directory
operationId: getDirectoryPermissions
x-required-scope: mailboxes:read
summary: Get directory permission settings
responses:
'200':
description: Directory permissions
content:
application/json:
schema:
$ref: '#/components/schemas/DirectoryPermissions'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
patch:
tags:
- Directory
operationId: updateDirectoryPermissions
x-required-scope: mailboxes:write
summary: Update directory permission settings
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
contact_view_access:
type: string
enum:
- all_users
- same_department
- admins_only
contact_edit_access:
type: string
enum:
- all_users
- admins_only
list_manage_access:
type: string
enum:
- all_users
- list_owners
- admins_only
external_sharing:
type: string
enum:
- allowed
- restricted
- disabled
responses:
'200':
description: Directory permissions updated
content:
application/json:
schema:
$ref: '#/components/schemas/DirectoryPermissions'
'400':
$ref: '#/components/responses/ProblemBadRequest'
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
/v1/directory-stats:
get:
tags:
- Directory
operationId: getDirectoryStats
x-required-scope: mailboxes:read
summary: Get directory statistics
responses:
'200':
description: Directory statistics
content:
application/json:
schema:
type: object
properties:
total_contacts:
type: integer
internal_users:
type: integer
external_contacts:
type: integer
synced_contacts:
type: integer
shared_lists:
type: integer
directory_groups:
type: integer
'401':
$ref: '#/components/responses/ProblemUnauthorized'
'403':
$ref: '#/components/responses/ProblemForbidden'
/v1/directory-activity:
get:
tags:
- Directory
operationId: getDirectoryActivity
x-required-scope: mailboxes:read
summary: Get recent directory activity
responses:
'200':
description: Recent directory activity
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
type:
type: string
message:
type: string
detail:
type: string
nullable: true
timestamp:
type: string
format: date-time
'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:
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
DirectoryPermissions:
type: object
required:
- tenant_id
- contact_view_access
- contact_edit_access
- list_manage_access
- external_sharing
properties:
tenant_id:
type: string
format: uuid
contact_view_access:
type: string
enum:
- all_users
- same_department
- admins_only
contact_edit_access:
type: string
enum:
- all_users
- admins_only
list_manage_access:
type: string
enum:
- all_users
- list_owners
- admins_only
external_sharing:
type: string
enum:
- allowed
- restricted
- disabled
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
GALSettings:
type: object
required:
- tenant_id
- gal_enabled
- hide_from_directory
- department_grouping
- search_visibility
- include_external_contacts
properties:
tenant_id:
type: string
format: uuid
gal_enabled:
type: boolean
hide_from_directory:
type: boolean
department_grouping:
type: boolean
search_visibility:
type: string
enum:
- all_users
- same_department
- admins_only
include_external_contacts:
type: boolean
last_index_rebuilt_at:
type: string
format: date-time
nullable: true
last_synced_at:
type: string
format: date-time
nullable: true
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
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