The Authentication API from Openwork — 19 operation(s) for authentication.
openapi: 3.1.0
info:
title: Den Admin Authentication API
description: 'OpenAPI spec for the Den control plane API.
Authentication:
- Use `Authorization: Bearer <session-token>` for user-authenticated routes that require a Den session.
- Use `x-api-key: <den-api-key>` for API-key-authenticated routes that accept organization API keys.
- Public routes like health and documentation do not require authentication.
Swagger tip: use the security schemes in the Authorize dialog to set either `bearerAuth` or `denApiKey` before trying protected endpoints.'
version: dev
servers:
- url: https://api.openworklabs.com
tags:
- name: Authentication
paths:
/v1/auth/login-options:
get:
operationId: getV1AuthLoginOptions
tags:
- Authentication
summary: Resolve deterministic login option
description: Returns the deterministic next authentication step for an email address. SSO is preferred before Google, password, GitHub compatibility, and new account creation.
responses:
'200':
description: Login option resolved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthLoginOptionsResponse'
'400':
description: The login option query parameters were invalid.
content:
application/json:
schema:
type: object
properties:
error:
type: string
const: invalid_request
required:
- error
parameters:
- in: query
name: email
schema:
type: string
format: email
pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
required: true
/v1/oauth-providers/{providerId}/client:
post:
operationId: postV1OauthProvidersByProviderIdClient
tags:
- Authentication
summary: Save an org's OAuth client for a provider
description: Admin-only. Lets an org bring its own OAuth app (client id + secret) for a native provider such as google-workspace, instead of relying on an OpenWork-owned client.
responses:
'200':
description: OAuth client saved.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthClientConfigResponse'
'400':
description: The request body or providerId was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Only workspace owners and admins can configure an OAuth client.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Unknown providerId.
content:
application/json:
schema:
$ref: '#/components/schemas/UnknownOAuthProviderError'
parameters:
- in: path
name: providerId
schema:
type: string
minLength: 1
maxLength: 255
required: true
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
clientId:
type: string
minLength: 1
maxLength: 512
clientSecret:
type: string
minLength: 1
maxLength: 4096
features:
type: array
items:
type: string
minLength: 1
maxLength: 128
tenantId:
type: string
minLength: 1
maxLength: 253
get:
operationId: getV1OauthProvidersByProviderIdClient
tags:
- Authentication
summary: Get an org's OAuth client configuration for a provider
description: Admin-only. Returns setup status, the saved OAuth client id when configured, selected permission features, the callback redirect URI, and the full scope list members will be asked to approve. Never returns the client secret.
responses:
'200':
description: OAuth client configuration.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthClientConfigDetailResponse'
'401':
description: The caller must be signed in.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Only workspace owners and admins can view an OAuth client configuration.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Unknown providerId.
content:
application/json:
schema:
$ref: '#/components/schemas/UnknownOAuthProviderError'
parameters:
- in: path
name: providerId
schema:
type: string
minLength: 1
maxLength: 255
required: true
/v1/oauth-providers/{providerId}/connect/start:
get:
operationId: getV1OauthProvidersByProviderIdConnectStart
tags:
- Authentication
summary: Begin connecting the calling member's account for a provider
description: Returns an authorize URL to redirect the member's browser to. Requires the org to have already saved an OAuth client for this provider.
responses:
'200':
description: Authorize URL to redirect to.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthConnectStartResponse'
'400':
description: Unknown providerId.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'404':
description: The org has not configured an OAuth client for this provider yet.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthClientNotConfiguredError'
parameters:
- in: path
name: providerId
schema:
type: string
minLength: 1
maxLength: 255
required: true
/v1/mcp-connections/google-workspace/connect/start:
get:
operationId: getV1McpConnectionsGoogleWorkspaceConnectStart
tags:
- Authentication
summary: Begin connecting the calling member to Google Workspace
description: 'Native-provider twin of the external MCP connect/start route: returns an authorize URL for the browser, using the OAuth client the org saved for this provider.'
responses:
'200':
description: Authorize URL, or already connected.
content:
application/json:
schema:
$ref: '#/components/schemas/NativeProviderConnectStartResponse'
'400':
description: The OAuth client configuration is incomplete.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'404':
description: The org has not configured an OAuth client for this provider yet.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthClientNotConfiguredError'
/v1/mcp-connections/microsoft-365/connect/start:
get:
operationId: getV1McpConnectionsMicrosoft365ConnectStart
tags:
- Authentication
summary: Begin connecting the calling member to Microsoft 365
description: 'Native-provider twin of the external MCP connect/start route: returns an authorize URL for the browser, using the OAuth client the org saved for this provider.'
responses:
'200':
description: Authorize URL, or already connected.
content:
application/json:
schema:
$ref: '#/components/schemas/NativeProviderConnectStartResponse'
'400':
description: The OAuth client configuration is incomplete.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'404':
description: The org has not configured an OAuth client for this provider yet.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthClientNotConfiguredError'
/v1/oauth-providers/{providerId}/connect/callback:
get:
operationId: getV1OauthProvidersByProviderIdConnectCallback
tags:
- Authentication
summary: OAuth callback for a provider
description: The provider redirects here with code+state after the member consents. Identity is carried entirely by the signed state token, not a session cookie, since the redirect may arrive in a fresh browser context. Serves a small static HTML page that deep-links back to OpenWork.
responses:
'200':
description: Connected — a static success page.
content:
text/html:
schema:
type: string
'400':
description: Missing or invalid code/state.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
parameters:
- in: path
name: providerId
schema:
type: string
minLength: 1
maxLength: 255
required: true
/v1/mcp-connections/discover:
post:
operationId: postV1McpConnectionsDiscover
tags:
- Authentication
summary: Discover external MCP connection requirements
description: Admin-only, side-effect-free requirements discovery. It performs no client registration, credential write, or connection creation.
responses:
'200':
description: Requirements discovery result.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpRequirementsDiscovery'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Only workspace owners and admins can discover MCP requirements.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'502':
description: Requirements discovery failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpRequirementsDiscoveryFailedError'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpRequirementsDiscoveryInput'
/v1/mcp-connections/{connectionId}/oauth/issuer-review:
post:
operationId: postV1McpConnectionsByConnectionIdOauthIssuerReview
tags:
- Authentication
summary: Review a changed External MCP OAuth issuer
description: Organization-admin-only. Repeats live OAuth discovery and either previews the issuers currently advertised by the MCP resource or explicitly confirms one. Confirmation never trusts an unadvertised issuer. Changing issuers invalidates issuer-bound OAuth clients and credentials so members reconnect cleanly.
responses:
'200':
description: Issuer review result.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpIssuerReviewResponse'
'400':
description: Invalid issuer review request.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Only workspace owners and admins can review OAuth issuers.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Unknown connection.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectionNotFoundError'
'409':
description: The connection changed or the requested issuer is not currently advertised.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectionConflictError'
'502':
description: Live OAuth discovery failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpRequirementsDiscoveryFailedError'
parameters:
- in: path
name: connectionId
schema:
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^emc_.*
required: true
description: Den TypeID with 'emc_' prefix and a 26-character base32 suffix.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpIssuerReviewInput'
/v1/mcp-connections/resolve:
post:
operationId: postV1McpConnectionsResolve
tags:
- Authentication
summary: Resolve a free-form query to an MCP server
description: Admin-only, side-effect-free smart resolution for the add-connection flow. Accepts a URL, a bare host, or a product name ("vercel"), matches curated presets, probes bounded well-known endpoint candidates through the SSRF-guarded discovery fetch, and returns the winning URL with its requirements discovery. It performs no client registration, credential write, or connection creation.
responses:
'200':
description: Resolution result (not_found is a successful outcome).
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpResolveResult'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Only workspace owners and admins can resolve MCP servers.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpResolveInput'
/v1/mcp-connections/{connectionId}/tools/call:
post:
operationId: postV1McpConnectionsByConnectionIdToolsCall
tags:
- Authentication
summary: Manually run a tool from an External MCP Connection
description: Workspace owner/admin diagnostic runner. Executes one named MCP tool with caller-supplied JSON arguments using the Den-managed shared credential or the calling admin's connected credential. Returns an ephemeral inspection of the actual tools/call HTTP request and response with credential and session headers redacted. The caller must already be granted access to the connection. Credentials, arguments, results, and inspection payloads are never written to logs.
responses:
'200':
description: The MCP tool completed.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectionToolRunResponse'
'400':
description: Invalid tool name or arguments.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: The caller must be a workspace owner/admin and have access to this connection.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Unknown connection.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectionNotFoundError'
'409':
description: The connection has no usable credential for this member.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectionNotReadyError'
'413':
description: The tool arguments exceeded the request size limit.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectionToolRequestTooLargeError'
'502':
description: The upstream MCP tool call failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectionToolRunFailedError'
parameters:
- in: path
name: connectionId
schema:
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^emc_.*
required: true
description: Den TypeID with 'emc_' prefix and a 26-character base32 suffix.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectionToolRunInput'
/v1/mcp-connections/{connectionId}:
put:
operationId: putV1McpConnectionsByConnectionId
tags:
- Authentication
summary: Edit an External MCP Connection
description: Organization-admin-only. Name and direct access changes preserve credentials. URL, authentication type, or credential-mode changes invalidate the old identity atomically. Secret fields are write-only optional replacements and are never returned. expectedUpdatedAt prevents stale edits.
responses:
'200':
description: Connection updated.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectionUpdatedResponse'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Only workspace owners and admins can edit MCP connections.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Unknown connection.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectionNotFoundError'
'409':
description: The edit is stale or changes marketplace-owned identity fields.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectionUpdateConflictError'
'502':
description: The proposed API-key or no-auth configuration could not be validated.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectionValidationFailedError'
parameters:
- in: path
name: connectionId
schema:
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^emc_.*
required: true
description: Den TypeID with 'emc_' prefix and a 26-character base32 suffix.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
expectedUpdatedAt:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
name:
type: string
minLength: 1
maxLength: 255
url:
type: string
maxLength: 2048
format: uri
authType:
type: string
enum:
- oauth
- apikey
- none
credentialMode:
type: string
enum:
- shared
- per_member
apiKey:
type: string
minLength: 1
maxLength: 4096
oauthClient:
type: object
properties:
clientId:
type: string
minLength: 1
maxLength: 512
clientSecret:
type: string
minLength: 1
maxLength: 4096
tokenEndpointAuthMethod:
type: string
enum:
- client_secret_basic
- client_secret_post
required:
- clientId
authorizationServerIssuer:
anyOf:
- type: string
maxLength: 2048
format: uri
- type: 'null'
requestedScopes:
maxItems: 100
type: array
items:
type: string
minLength: 1
maxLength: 255
access:
$ref: '#/components/schemas/ExternalMcpConnectionAccessInput'
required:
- expectedUpdatedAt
- name
- url
- authType
- credentialMode
- access
delete:
operationId: deleteV1McpConnectionsByConnectionId
tags:
- Authentication
summary: Remove an External MCP Connection
responses:
'200':
description: Removed.
'401':
description: The caller must be signed in.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Only workspace owners and admins can remove MCP connections.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Unknown connection.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectionNotFoundError'
parameters:
- in: path
name: connectionId
schema:
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^emc_.*
required: true
description: Den TypeID with 'emc_' prefix and a 26-character base32 suffix.
/v1/mcp-connections/{connectionId}/disconnect:
post:
operationId: postV1McpConnectionsByConnectionIdDisconnect
tags:
- Authentication
summary: Disconnect (clear credentials for) an External MCP Connection without removing it
description: Admin-only. Signs out every shared or per-member account stored for this connection, while preserving the connection row, access grants, OAuth client configuration, and plugin bindings.
responses:
'200':
description: Disconnected.
'401':
description: The caller must be signed in.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Only workspace owners and admins can disconnect MCP connections.
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Unknown connection.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectionNotFoundError'
parameters:
- in: path
name: connectionId
schema:
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^emc_.*
required: true
description: Den TypeID with 'emc_' prefix and a 26-character base32 suffix.
/v1/mcp-connections/{connectionId}/disconnect-my-account:
post:
operationId: postV1McpConnectionsByConnectionIdDisconnectMyAccount
tags:
- Authentication
summary: Disconnect the calling member's account for a per-member External MCP Connection
description: Removes only the caller's connected account for this MCP connection. The org-level connection, access grants, OAuth client configuration, and other members' accounts are preserved.
responses:
'200':
description: Disconnected.
'400':
description: This connection does not use per-member credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
'401':
description: The caller must be signed in.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'404':
description: Unknown connection or nothing was connected.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectionNotFoundError'
parameters:
- in: path
name: connectionId
schema:
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^emc_.*
required: true
description: Den TypeID with 'emc_' prefix and a 26-character base32 suffix.
/v1/mcp-connections/{connectionId}/connect/start:
get:
operationId: getV1McpConnectionsByConnectionIdConnectStart
tags:
- Authentication
summary: Begin the OAuth handshake for an External MCP Connection
description: Runs RFC 9728 discovery, dynamic client registration if needed, and returns an authorize URL to redirect the admin's browser to.
responses:
'200':
description: Authorize URL, or already connected.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectStartResponse'
'401':
description: The caller must be signed in.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'404':
description: Unknown connection.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectionNotFoundError'
'409':
description: The OAuth connection requires provider or issuer configuration before connecting.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectStartConflictError'
'502':
description: OAuth handshake failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalMcpConnectStartFailedError'
parameters:
- in: path
name: connectionId
schema:
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^emc_.*
required: true
description: Den TypeID with 'emc_' prefix and a 26-character base32 suffix.
/v1/mcp-connections/oauth/callback:
get:
operationId: getV1McpConnectionsOauthCallback
tags:
- Authentication
summary: Shared OAuth callback for External MCP Connections
description: Deployment-wide callback. Organization, member, and connection routing are derived exclusively from signed state.
responses:
'200':
description: Connected — a static success page.
content:
text/html:
schema:
type: string
'400':
description: Missing or invalid code/state.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
/v1/mcp-connections/{connectionId}/connect/callback:
get:
operationId: getV1McpConnectionsByConnectionIdConnectCallback
tags:
- Authentication
summary: OAuth callback for an External MCP Connection
description: The external MCP server redirects here with code+state after the admin consents. Serves a small static HTML page — the admin's Den tab in the background polls connection status and never needs this response body.
responses:
'200':
description: Connected — a static success page.
content:
text/html:
schema:
type: string
'400':
description: Missing or invalid code/state.
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidRequestError'
parameters:
- in: path
name: connectionId
schema:
format: typeid
type: string
minLength: 30
maxLength: 30
pattern: ^emc_.*
required: true
description: Den TypeID with 'emc_' prefix and a 26-character base32 suffix.
/v1/telegram/connection:
get:
operationId: getV1TelegramConnection
tags:
- Authentication
summary: Get the organization Telegram connection
description: Returns redacted bot, worker, webhook, and private-chat pairing status. Bot tokens and webhook s
# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openwork/refs/heads/main/openapi/openwork-authentication-api-openapi.yml