> ## Documentation Index > Fetch the complete documentation index at: https://docs.lumos.com/llms.txt > Use this file to discover all available pages before exploring further. # /{connector_id}/handle_authorization_callback > Handle Authorization Callback This operation processes the OAuth callback to exchange the authorization code for access and refresh tokens. ## OpenAPI ````yaml openapi/lumos-connectors.json POST /{connector_id}/handle_authorization_callback openapi: 3.0.0 info: title: Lumos Connectors description: >- # The Lumos Connector API ## Introduction The Lumos Connector API is a standardized interface for Identity and Access Management (IAM) operations across various third-party systems. It enables seamless integration between Lumos and external applications by providing a consistent set of operations called **capabilities**. Each integration (referred to as a "connector") implements these capabilities to work with different third-party API providers, focusing primarily on: - User access management - License and cost tracking - User activity monitoring ## Core Components ### Connectors A connector is a specialized library that acts as a bridge between Lumos and third-party applications. It handles: - Translation of Lumos requests into app-specific API calls - Conversion of app-specific responses into standardized Lumos formats - Authentication and authorization flows - Data format transformations ### Capabilities Capabilities are standardized operations that each connector can implement. They provide: - Consistent interfaces across different connectors - Predictable behavior patterns - Standardized error handling - Unified data structures ## Data Model ### Accounts Accounts represent individual users or service accounts within a system. They serve as the primary entities for access management and support lifecycle operations such as creation, activation, deactivation, and deletion. Accounts can be associated with multiple entitlements and are typically identified by a unique account ID within the system. ### Entitlements Entitlements represent a permission or capability that can be granted to user accounts, such as a license or access level. They define specific permissions, access rights, or memberships and are always associated with a resource, which may be global or specific. Entitlements are categorized by `entitlement_type` (e.g., licenses, roles, permissions, group memberships) and have defined constraints for minimum and maximum assignments. The naming of entitlements may vary, such as using "membership" for group associations. ### Resources Resources represent entities within an application that can be accessed or managed. They are identified by a unique `resource_type` within each app and include a global resource (represented by an empty string) for top-level entities. Resources can represent hierarchical structures, such as Workspaces containing Users and Groups, and serve as the context for entitlement assignments. The usage of Resource IDs depends on the specific hierarchy, with an empty string for global resources and specific IDs (e.g., Workspace ID) for nested resources. ### Associations Associations define relationships from accounts to entitlements (which are resource specific). They follow a hierarchical structure of Account -> Entitlement -> Resource, with no direct account-to-resource associations allowed. Associations enable flexible access control models. Note: The specific structure and use of resources and entitlements may vary depending on the integrated system's architecture and access model. ## How to Use This API 1. Discover available connectors 2. Learn about a specific connector 3. Configure a connector 4. (optional) Authenticate with OAuth 5. Read data from the connected tenant 6. Write (update) data in the connected tenant ## Authenticating with a Connector ### Authentication Methods Connectors support two main authentication categories: ### 1. Shared Secret Authentication - API Keys / Tokens - Basic Authentication (username/password) ### 2. OAuth-based Authentication The API supports two OAuth flow types: #### Authorization Code Flow (3-legged OAuth) Requires a multi-step flow: 1. **Authorization URL** - Call `get_authorization_url` to start the OAuth flow - Redirect user to the returned authorization URL 2. **Handle Callback** - Process the OAuth callback using `handle_authorization_callback` - Receive access and refresh tokens 3. **Token Management** - Use `refresh_access_token` to maintain valid access - Store refresh tokens securely #### Client Credentials Flow (2-legged OAuth) Suitable for machine-to-machine authentication: 1. **Direct Token Request** - Call `handle_client_credentials_request` with client credentials - Receive access token (and optionally refresh token) 2. **Token Management** - Use `refresh_access_token` to maintain valid access (if refresh tokens are supported) - Store tokens securely The flow type is configured in the connector settings and determines which capabilities are available. Both flows support customizable authentication methods (Basic Auth or request body) and different request formats (JSON, form data, or query parameters). ### Validation After obtaining credentials: 1. Call `validate_credentials` to verify authentication 2. Retrieve the unique tenant ID for the authenticated organization ### Authentication Schema Each connector's `info.authentication_schema` defines: - Required credential fields - Field formats and constraints - OAuth scopes (if applicable) ## Pagination Lumos connectors implement a standardized pagination mechanism to handle large datasets efficiently. The pagination system uses opaque tokens to maintain state across requests. ### How Pagination Works 1. **Request Format** Every request can include an optional `page` parameter: ```typescript { "page": { "token": string, // Optional: opaque token from previous response "size": number // Optional: number of items per page } } ``` 2. **Response Format** Paginated responses include a `page` field: ```typescript { "response": T[], // Array of items "page": { "token": string, // Token for the next page "size": number // Items per page } } ``` ### Using Pagination 1. **Initial Request** - Make the first request without a page token - Optionally specify a page size 2. **Subsequent Requests** - Include the `token` from the previous response - Keep the same page size for consistency 3. **End of Data** - When there's no more data, the response won't include a page token ### Example Flow ```typescript // First request POST /connectors/pagerduty/list_accounts { "page": { "size": 100 } } // Response { "response": [...], "page": { "token": "eyJwYWdlIjogMn0=", "size": 100 } } // Next request POST /connectors/pagerduty/list_accounts { "page": { "token": "eyJwYWdlIjogMn0=", "size": 100 } } ``` ### Implementation Notes - Page tokens are opaque and should be treated as black boxes - Tokens may encode various information (page numbers, cursors, etc.) - The same page size should be used throughout a pagination sequence - Invalid or expired tokens will result in an error response version: 0.0.0 servers: [] security: [] tags: - name: Learning about connectors - name: Open API Specification - name: Read Capabilities - name: OAuth Capabilities - name: Write Capabilities paths: /{connector_id}/handle_authorization_callback: post: tags: - OAuth Capabilities description: >- Handle Authorization Callback This operation processes the OAuth callback to exchange the authorization code for access and refresh tokens. operationId: handle_authorization_callback parameters: - name: connector_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/HandleAuthorizationCallbackRequest' responses: '200': description: The request has succeeded. content: application/json: schema: anyOf: - $ref: '#/components/schemas/HandleAuthorizationCallbackResponse' - $ref: '#/components/schemas/ErrorResponse' components: schemas: HandleAuthorizationCallbackRequest: type: object allOf: - type: object required: - request properties: request: allOf: - $ref: '#/components/schemas/HandleAuthorizationCallback' description: The main request payload. include_raw_data: type: boolean description: Whether to include raw data in the response. page: allOf: - $ref: '#/components/schemas/Page' description: Pagination information for the request. settings: type: object additionalProperties: {} description: |- Connector-specific settings for the request. These are settings that are shared across all capabilities. Usually contain additional required configuration options not specified by the capability schema. description: Generic request model. HandleAuthorizationCallbackResponse: type: object allOf: - type: object required: - response properties: response: $ref: '#/components/schemas/OauthCredentials' raw_data: {} page: $ref: '#/components/schemas/Page' description: >- Response containing the main response payload, raw data, and pagination information. description: >- Response containing the OAuth credentials after handling an authorization callback. ErrorResponse: type: object required: - is_error - error properties: is_error: type: boolean description: Always true for error responses. default: true error: allOf: - $ref: '#/components/schemas/Error' description: The error details. raw_data: type: object additionalProperties: {} description: Raw data associated with the error, if any. page: allOf: - $ref: '#/components/schemas/Page' description: Pagination information, if applicable. description: Error details and metadata returned when an operation fails. HandleAuthorizationCallback: type: object required: - client_id - client_secret - redirect_uri_with_code properties: credential_id: type: string description: The credential ID assigned to these credentials. client_id: type: string description: The OAuth client ID provided by the third-party service. client_secret: type: string description: The OAuth client secret associated with the client ID. redirect_uri_with_code: type: string description: >- The redirect URI containing the authorization code returned by the OAuth provider. state: type: string description: (Optional) A state parameter for security validation. code_verifier: type: string description: >- A code verifier for PKCE. This is returned from the get_authorization_url operation if PKCE is enabled. description: Parameters for handling an OAuth2 authorization callback. x-capability-category: authorization Page: type: object properties: token: type: string description: |- Opaque token representing the next page of results. Include this token in subsequent requests to retrieve the next page. size: type: integer format: int32 description: |- Number of items to return per page. This should remain consistent throughout a pagination sequence. description: Pagination parameters for requests and responses. OauthCredentials: type: object required: - access_token - token_type properties: access_token: type: string description: >- The token used for authenticating API requests, providing access to the API. refresh_token: type: string description: >- (Optional) A token used to refresh the access token, extending the session without re-authentication. token_type: allOf: - $ref: '#/components/schemas/TokenType' description: >- The type of token, usually "bearer", indicating how the token should be used. state: type: string description: >- (Optional) A state parameter for security validation, ensuring the response matches the request. description: >- OAuth credentials model. Enough authentication material to enable a capability, e.g. List Accounts, for an OAuth-based connector. Error: type: object required: - message - error_code - app_id properties: message: type: string description: A human-readable string explaining what went wrong. example: Authentication credentials didn't work status_code: type: integer description: |- An http status code (if applicable) corresponding to the underlying app's HTTP response that triggered this error. example: 401 app_error_code: type: string description: |- An application-specific code string that can tell us more details about the underlying application code or request that triggered the error. example: my_integration.token_expired error_code: allOf: - $ref: '#/components/schemas/ErrorCode' description: >- A standard error code used by Lumos callers to respond to this error. example: unauthenticated app_id: type: string description: The ID of the app where the error occurred. example: pagerduty raised_by: type: string description: What type of exception triggered this error (if any) example: ConnectorError raised_in: type: string description: Where the exception was raised example: my_integration.integration:list_accounts description: An error that occurred during an operation. TokenType: type: string enum: - bearer ErrorCode: type: string enum: - not_found - internal_error - api_error - unauthorized - bad_request - permission_denied - not_implemented - unexpected_error - unsupported_operation - unknown_value - invalid_value - bad_gateway - unauthenticated - request_timeout - connection_timeout - connection_rejected - rate_limit - authentication_expired - service_error - invalid_response - client_call_error - connection_closed - creds_revoked - invalid_page_token - integration_missing_parameter description: >- Enum representing various error codes that can be returned by the connector. ````