Documentation
API reference
A complete, read-only view of the Authlane OpenAPI 3.1 control-plane contract.
Operations
Production server: https://app.authlane.io. Tenant API keys stay in trusted server code; hosted connect routes use short-lived connect sessions.
GET/api/v1/catalog/servicesList tenant-enabled services
- Operation ID
listCatalogServices- Authentication
- ApiKey
- Required scope
catalog:read- Responses
- 200, 401, 403, 429
Response example
{
"data": [
{
"id": "github",
"name": "GitHub",
"authType": "oauth2",
"enabled": true,
"config": {}
},
{
"id": "slack",
"name": "Slack",
"authType": "oauth2",
"enabled": true,
"config": {}
}
],
"error": null
}GET/api/v1/users/{externalUserId}/connectionsList effective connection states
- Operation ID
listUserConnections- Authentication
- ApiKey
- Required scope
connections:read- Responses
- 200, 400, 401, 403, 429
Response example
{
"data": [
{
"serviceId": "github",
"status": "connected",
"connected": true,
"expiresAt": "2026-08-01T12:00:00.000Z",
"connectedAt": "2026-07-18T10:00:00.000Z",
"lastCheckedAt": null,
"errorCode": null
},
{
"serviceId": "slack",
"status": "disconnected",
"connected": false,
"expiresAt": null,
"connectedAt": null,
"lastCheckedAt": null,
"errorCode": null
}
],
"error": null
}GET/api/v1/users/{externalUserId}/capabilitiesGet states and tool definitions in one hot read
- Operation ID
getUserCapabilities- Authentication
- ApiKey
- Required scope
connections:read- Responses
- 200, 400, 401, 403, 429
Response example
{
"data": {
"externalUserId": "user_123",
"format": "mcp",
"version": "cafebabe",
"services": [
{
"serviceId": "github",
"status": "connected",
"connected": true,
"expiresAt": "2026-08-01T12:00:00.000Z",
"tools": [
{
"name": "github_create_issue",
"description": "Create an issue in a GitHub repository.",
"inputSchema": {
"type": "object",
"properties": {
"owner": {
"type": "string"
},
"repo": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"owner",
"repo",
"title"
]
}
}
]
}
]
},
"error": null
}GET/api/v1/users/{externalUserId}/toolsList definitions for usable connections
- Operation ID
listUserTools- Authentication
- ApiKey
- Required scope
connections:read- Responses
- 200, 400, 401, 403, 429
Response example
{
"data": {
"tools": [
{
"name": "github_create_issue",
"description": "Create an issue in a GitHub repository.",
"inputSchema": {
"type": "object",
"properties": {
"owner": {
"type": "string"
},
"repo": {
"type": "string"
},
"title": {
"type": "string"
}
},
"required": [
"owner",
"repo",
"title"
]
}
}
],
"version": "cafebabe"
},
"error": null
}POST/api/v1/users/{externalUserId}/connections/{serviceId}/credential-leasesIssue access-only credential material
- Operation ID
createCredentialLease- Authentication
- ApiKey
- Required scope
credentials:issue- Responses
- 201, 400, 401, 403, 404, 409, 429, 500
Response example
{
"data": {
"type": "oauth2",
"leaseId": "550e8400-e29b-41d4-a716-446655440000",
"accessToken": "provider-access-token-redacted",
"tokenType": "Bearer",
"scopes": [
"repo",
"user:email"
],
"expiresAt": "2026-07-18T12:05:00.000Z"
},
"error": null
}POST/api/v1/connect-sessionsCreate a browser handoff session
- Operation ID
createConnectSession- Authentication
- ApiKey
- Required scope
connect-sessions:create- Responses
- 201, 400, 401, 403, 429
Request example
{
"externalUserId": "user_123",
"allowedServices": [],
"allowedOrigin": "https://app.example.com",
"expiresInSeconds": 600
}Response example
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"token": "acs_redacted",
"url": "https://app.authlane.io/connect?origin=https%3A%2F%2Fapp.example.com#session=acs_redacted",
"expiresAt": "2026-07-18T12:10:00.000Z"
},
"error": null
}POST/api/v1/connect/sessionResolve a hosted connect session
- Operation ID
getHostedConnectSession- Authentication
- ConnectSession
- Responses
- 200, 401, 403, 429
Request example
{
"parentOrigin": "https://app.example.com"
}Response example
{
"data": {
"externalUserId": "user_123",
"expiresAt": "2026-07-18T12:10:00.000Z",
"services": [
{
"id": "github",
"name": "GitHub",
"authType": "oauth2",
"status": "connected"
},
{
"id": "slack",
"name": "Slack",
"authType": "oauth2",
"status": "disconnected"
}
]
},
"error": null
}POST/api/v1/connect/{serviceId}/authorizeBegin provider authorization
- Operation ID
authorizeConnection- Authentication
- ConnectSession
- Responses
- 200, 400, 401, 403, 404, 409, 429
Request example
{
"parentOrigin": "https://app.example.com"
}Response example
{
"data": {
"authorizationUrl": "https://github.com/login/oauth/authorize?client_id=redacted&state=redacted&code_challenge=redacted&code_challenge_method=S256"
},
"error": null
}DELETE/api/v1/connect/{serviceId}Disconnect an external user's service
- Operation ID
disconnectConnection- Authentication
- ConnectSession
- Responses
- 200, 401, 403, 429
Request example
{
"parentOrigin": "https://app.example.com"
}Response example
{
"data": {
"disconnected": true
},
"error": null
}GET/api/v1/oauth/{serviceId}/callbackValidate state and exchange the provider code
- Operation ID
oauthCallback- Authentication
- Public callback
- Responses
- 302, 400, 409, 429
Response example
{
"Location": "https://app.authlane.io/connect/callback?status=connected&serviceId=github"
}Webhooks
Lifecycle webhooks are signed with the timestamp and exact raw body. Verify the HMAC before parsing JSON, then deduplicate deliveries with the idempotency key.
Webhook example
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "connection.connected",
"createdAt": "2026-07-18T12:00:00.000Z",
"data": {
"externalUserId": "user_123",
"serviceId": "github",
"connectionId": "6ba7b810-9dad-41d1-80b4-00c04fd430c8"
}
}Webhook contract
{
"connectionLifecycle": {
"post": {
"operationId": "receiveConnectionLifecycleEvent",
"summary": "Receive a signed connection lifecycle event",
"parameters": [
{
"name": "X-Authlane-Signature",
"in": "header",
"required": true,
"description": "Hex HMAC-SHA256 of `<timestamp>.<raw-body>` using the webhook secret.",
"schema": {
"type": "string",
"pattern": "^[0-9a-f]{64}$"
}
},
{
"name": "X-Authlane-Timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-Authlane-Event",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": [
"connection.connected",
"connection.disconnected",
"connection.expired",
"connection.refreshed",
"connection.error"
]
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id",
"type",
"createdAt",
"data"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"type": {
"type": "string",
"enum": [
"connection.connected",
"connection.disconnected",
"connection.expired",
"connection.refreshed",
"connection.error"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"data": {
"type": "object",
"required": [
"externalUserId",
"serviceId"
],
"properties": {
"externalUserId": {
"type": "string"
},
"serviceId": {
"type": "string"
},
"connectionId": {
"type": "string",
"format": "uuid"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"errorCode": {
"type": "string"
}
}
}
}
},
"examples": {
"connection": {
"summary": "Signed connection lifecycle delivery",
"value": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"type": "connection.connected",
"createdAt": "2026-07-18T12:00:00.000Z",
"data": {
"externalUserId": "user_123",
"serviceId": "github",
"connectionId": "6ba7b810-9dad-41d1-80b4-00c04fd430c8"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Event accepted"
},
"204": {
"description": "Event accepted without a response body"
}
}
}
}
}Schemas
AuthlaneError
{
"type": "object",
"required": [
"message",
"code"
],
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string"
},
"hint": {
"type": "string"
},
"docUrl": {
"type": "string",
"format": "uri"
},
"statusCode": {
"type": "integer",
"minimum": 100,
"maximum": 599
}
}
}ErrorResult
{
"type": "object",
"required": [
"data",
"error"
],
"properties": {
"data": {
"type": "null"
},
"error": {
"type": "object",
"required": [
"message",
"code"
],
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string"
},
"hint": {
"type": "string"
},
"docUrl": {
"type": "string",
"format": "uri"
},
"statusCode": {
"type": "integer",
"minimum": 100,
"maximum": 599
}
}
}
}
}Service
{
"type": "object",
"required": [
"id",
"name",
"authType",
"enabled"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"authType": {
"type": "string",
"enum": [
"oauth2",
"api_key"
]
},
"enabled": {
"type": "boolean"
}
}
}CatalogResult
{
"type": "object",
"required": [
"data",
"error"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"authType",
"enabled"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"authType": {
"type": "string",
"enum": [
"oauth2",
"api_key"
]
},
"enabled": {
"type": "boolean"
}
}
}
},
"error": {
"type": "null"
}
}
}Connection
{
"type": "object",
"required": [
"serviceId",
"status",
"connected",
"expiresAt"
],
"properties": {
"serviceId": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"disconnected",
"pending",
"connected",
"expired",
"error"
]
},
"connected": {
"type": "boolean"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"connectedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"errorCode": {
"type": [
"string",
"null"
]
}
}
}ConnectionsResult
{
"type": "object",
"required": [
"data",
"error"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"serviceId",
"status",
"connected",
"expiresAt"
],
"properties": {
"serviceId": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"disconnected",
"pending",
"connected",
"expired",
"error"
]
},
"connected": {
"type": "boolean"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"connectedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"errorCode": {
"type": [
"string",
"null"
]
}
}
}
},
"error": {
"type": "null"
}
}
}JsonSchema
{
"type": "object",
"additionalProperties": true
}ToolDefinition
{
"oneOf": [
{
"type": "object",
"required": [
"name",
"description",
"inputSchema"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"inputSchema": {
"type": "object",
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"name",
"description",
"parameters"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"parameters": {
"type": "object",
"additionalProperties": true
}
}
}
]
}McpToolDefinition
{
"type": "object",
"required": [
"name",
"description",
"inputSchema"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"inputSchema": {
"type": "object",
"additionalProperties": true
}
}
}OpenAIFunctionDefinition
{
"type": "object",
"required": [
"name",
"description",
"parameters"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"parameters": {
"type": "object",
"additionalProperties": true
}
}
}CapabilityService
{
"allOf": [
{
"type": "object",
"required": [
"serviceId",
"status",
"connected",
"expiresAt"
],
"properties": {
"serviceId": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"disconnected",
"pending",
"connected",
"expired",
"error"
]
},
"connected": {
"type": "boolean"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"connectedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"errorCode": {
"type": [
"string",
"null"
]
}
}
},
{
"type": "object",
"required": [
"tools"
],
"properties": {
"tools": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"name",
"description",
"inputSchema"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"inputSchema": {
"type": "object",
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"name",
"description",
"parameters"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"parameters": {
"type": "object",
"additionalProperties": true
}
}
}
]
}
}
}
}
]
}CapabilitiesResult
{
"type": "object",
"required": [
"data",
"error"
],
"properties": {
"data": {
"type": "object",
"required": [
"externalUserId",
"format",
"version",
"services"
],
"properties": {
"externalUserId": {
"type": "string"
},
"format": {
"type": "string",
"enum": [
"mcp",
"openai"
]
},
"version": {
"type": "string"
},
"services": {
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"required": [
"serviceId",
"status",
"connected",
"expiresAt"
],
"properties": {
"serviceId": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"disconnected",
"pending",
"connected",
"expired",
"error"
]
},
"connected": {
"type": "boolean"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"connectedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"lastCheckedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"errorCode": {
"type": [
"string",
"null"
]
}
}
},
{
"type": "object",
"required": [
"tools"
],
"properties": {
"tools": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"name",
"description",
"inputSchema"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"inputSchema": {
"type": "object",
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"name",
"description",
"parameters"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"parameters": {
"type": "object",
"additionalProperties": true
}
}
}
]
}
}
}
}
]
}
}
}
},
"error": {
"type": "null"
}
}
}ToolsResult
{
"type": "object",
"required": [
"data",
"error"
],
"properties": {
"data": {
"oneOf": [
{
"type": "object",
"required": [
"tools",
"version"
],
"properties": {
"tools": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"description",
"inputSchema"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"inputSchema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"version": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"functions",
"version"
],
"properties": {
"functions": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"description",
"parameters"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"parameters": {
"type": "object",
"additionalProperties": true
}
}
}
},
"version": {
"type": "string"
}
}
}
]
},
"error": {
"type": "null"
}
}
}CredentialLeaseResult
{
"type": "object",
"required": [
"data",
"error"
],
"properties": {
"data": {
"oneOf": [
{
"type": "object",
"required": [
"type",
"leaseId",
"accessToken",
"tokenType",
"scopes",
"expiresAt"
],
"properties": {
"type": {
"const": "oauth2"
},
"leaseId": {
"type": "string",
"format": "uuid"
},
"accessToken": {
"type": "string"
},
"tokenType": {
"type": "string"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
},
{
"type": "object",
"required": [
"type",
"leaseId",
"value",
"placement",
"expiresAt"
],
"properties": {
"type": {
"const": "api_key"
},
"leaseId": {
"type": "string",
"format": "uuid"
},
"value": {
"type": "string"
},
"placement": {
"oneOf": [
{
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"const": "header"
},
"name": {
"type": "string"
},
"prefix": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"const": "query"
},
"name": {
"type": "string"
}
}
}
]
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
]
},
"error": {
"type": "null"
}
}
}OAuthCredentialLease
{
"type": "object",
"required": [
"type",
"leaseId",
"accessToken",
"tokenType",
"scopes",
"expiresAt"
],
"properties": {
"type": {
"const": "oauth2"
},
"leaseId": {
"type": "string",
"format": "uuid"
},
"accessToken": {
"type": "string"
},
"tokenType": {
"type": "string"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}ApiKeyCredentialLease
{
"type": "object",
"required": [
"type",
"leaseId",
"value",
"placement",
"expiresAt"
],
"properties": {
"type": {
"const": "api_key"
},
"leaseId": {
"type": "string",
"format": "uuid"
},
"value": {
"type": "string"
},
"placement": {
"oneOf": [
{
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"const": "header"
},
"name": {
"type": "string"
},
"prefix": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"const": "query"
},
"name": {
"type": "string"
}
}
}
]
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}ApiKeyPlacement
{
"oneOf": [
{
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"const": "header"
},
"name": {
"type": "string"
},
"prefix": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"type",
"name"
],
"properties": {
"type": {
"const": "query"
},
"name": {
"type": "string"
}
}
}
]
}CreateConnectSession
{
"type": "object",
"required": [
"externalUserId",
"allowedServices",
"allowedOrigin"
],
"properties": {
"externalUserId": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"allowedServices": {
"type": "array",
"description": "An empty array snapshots all services currently enabled for the tenant.",
"items": {
"type": "string",
"pattern": "^[a-z0-9-]+$"
}
},
"allowedOrigin": {
"type": "string",
"format": "uri"
},
"expiresInSeconds": {
"type": "integer",
"minimum": 60,
"maximum": 900,
"default": 600
},
"reauthenticatedAt": {
"type": "string",
"format": "date-time",
"description": "Required for disconnect and accepted only within the recent-reauthentication window."
}
}
}ConnectSessionResult
{
"type": "object",
"required": [
"data",
"error"
],
"properties": {
"data": {
"type": "object",
"required": [
"id",
"token",
"url",
"expiresAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"token": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
}
},
"error": {
"type": "null"
}
}
}HostedConnectService
{
"type": "object",
"required": [
"id",
"name",
"authType",
"status"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"authType": {
"type": "string",
"enum": [
"oauth2",
"api_key"
]
},
"status": {
"type": "string",
"enum": [
"disconnected",
"pending",
"connected",
"expired",
"error"
]
}
}
}HostedConnectSessionResult
{
"type": "object",
"required": [
"data",
"error"
],
"properties": {
"data": {
"type": "object",
"required": [
"externalUserId",
"services",
"expiresAt"
],
"properties": {
"externalUserId": {
"type": "string"
},
"services": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"authType",
"status"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"authType": {
"type": "string",
"enum": [
"oauth2",
"api_key"
]
},
"status": {
"type": "string",
"enum": [
"disconnected",
"pending",
"connected",
"expired",
"error"
]
}
}
}
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
}
},
"error": {
"type": "null"
}
}
}ConnectAction
{
"type": "object",
"required": [
"parentOrigin"
],
"properties": {
"parentOrigin": {
"type": "string",
"format": "uri"
}
}
}AuthorizeResult
{
"type": "object",
"required": [
"data",
"error"
],
"properties": {
"data": {
"type": "object",
"required": [
"authorizationUrl"
],
"properties": {
"authorizationUrl": {
"type": "string",
"format": "uri"
}
}
},
"error": {
"type": "null"
}
}
}DisconnectResult
{
"type": "object",
"required": [
"data",
"error"
],
"properties": {
"data": {
"type": "object",
"required": [
"disconnected"
],
"properties": {
"disconnected": {
"type": "boolean"
}
}
},
"error": {
"type": "null"
}
}
}WebhookEventName
{
"type": "string",
"enum": [
"connection.connected",
"connection.disconnected",
"connection.expired",
"connection.refreshed",
"connection.error"
]
}WebhookEvent
{
"type": "object",
"required": [
"id",
"type",
"createdAt",
"data"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"type": {
"type": "string",
"enum": [
"connection.connected",
"connection.disconnected",
"connection.expired",
"connection.refreshed",
"connection.error"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"data": {
"type": "object",
"required": [
"externalUserId",
"serviceId"
],
"properties": {
"externalUserId": {
"type": "string"
},
"serviceId": {
"type": "string"
},
"connectionId": {
"type": "string",
"format": "uuid"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"errorCode": {
"type": "string"
}
}
}
}
}WebhookEventData
{
"type": "object",
"required": [
"externalUserId",
"serviceId"
],
"properties": {
"externalUserId": {
"type": "string"
},
"serviceId": {
"type": "string"
},
"connectionId": {
"type": "string",
"format": "uuid"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"errorCode": {
"type": "string"
}
}
}