Composio Authentication API

openapi: 3.0.0
info:
  version: 3.0.0
  title: Composio Platform Account Management Authentication API
  description: Authentication related endpoints
  contact:
    name: Composio Support
    url: https://composio.dev/support
    email: support@composio.dev
  license:
    name: Proprietary
    url: https://composio.dev/terms
servers:
- url: https://backend.composio.dev
  description: PRODUCTION API
tags:
- name: Authentication
  description: Authentication related endpoints
paths:
  /api/v3/auth/session/info:
    get:
      summary: Get current user session information
      description: Retrieves detailed information about the current authenticated user session, including project details, organization membership, and API key information if applicable. This endpoint is useful for verifying authentication status and retrieving contextual information about the authenticated user and their access privileges.
      tags:
      - Authentication
      operationId: getAuthSessionInfo
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      responses:
        '200':
          description: Session is valid and active. Returns detailed information about the authenticated user, their project, and organization.
          content:
            application/json:
              schema:
                type: object
                properties:
                  project:
                    type: object
                    nullable: true
                    properties:
                      auto_id:
                        type: number
                        description: Internal auto-incrementing ID for the project
                        example: 12345
                      id:
                        type: string
                        description: UUID identifier for the project
                        example: 550e8400-e29b-41d4-a716-446655440000
                      org_id:
                        type: string
                        description: Organization UUID that this project belongs to
                        example: 550e8400-e29b-41d4-a716-446655440001
                      name:
                        type: string
                        description: User-defined name for the project
                        example: Production API
                      email:
                        type: string
                        description: Email address used for project notifications
                        example: project-123@composio.dev
                      nano_id:
                        type: string
                        format: projectId
                        description: Short, URL-friendly unique identifier for the project
                        example: pr_1a2b3c4d5e6f
                      created_at:
                        type: string
                        description: Date and time when the project was created
                        example: '2023-05-16T14:30:00.000Z'
                      updated_at:
                        type: string
                        description: Date and time when the project was last modified
                        example: '2023-05-18T09:15:30.000Z'
                      webhook_url:
                        type: string
                        nullable: true
                        description: Endpoint URL for trigger webhook notifications
                        example: https://example.com/webhook
                      event_webhook_url:
                        type: string
                        nullable: true
                        description: Endpoint URL for event webhook notifications
                        example: https://example.com/events
                      webhook_secret:
                        type: string
                        nullable: true
                        description: Secret used to verify webhook signatures
                        example: whsec_a1b2c3d4e5f6g7h8i9j0
                      triggers_enabled:
                        type: boolean
                        description: Flag indicating if triggers are enabled for this project
                        example: true
                      last_subscribed_at:
                        type: string
                        nullable: true
                        description: Date and time when the project last subscribed to updates
                        example: '2023-05-17T10:00:00.000Z'
                      deleted:
                        type: boolean
                        description: Flag indicating if the project has been deleted
                        example: false
                      is_new_webhook:
                        type: boolean
                        description: 'Deprecated: Please refer to webhook_version instead. True indicates if the webhook configuration is using the previous new format (V2). False indicates the oldest format (V1)'
                        example: true
                        deprecated: true
                      webhook_version:
                        type: string
                        enum:
                        - V1
                        - V2
                        - V3
                        description: Version of the webhook configuration
                        example: V2
                      org:
                        type: object
                        properties:
                          id:
                            type: string
                            format: orgId
                            description: Short, URL-friendly unique identifier for the organization
                            example: ok_1a2b3c4d5e6f
                          name:
                            type: string
                            description: User-defined name for the organization
                            example: Acme Corp
                          plan:
                            type: string
                            description: Current subscription plan level
                            example: BUSINESS
                        required:
                        - id
                        - name
                        - plan
                        description: Organization details
                    required:
                    - auto_id
                    - id
                    - org_id
                    - name
                    - email
                    - nano_id
                    - created_at
                    - updated_at
                    - webhook_url
                    - event_webhook_url
                    - webhook_secret
                    - triggers_enabled
                    - last_subscribed_at
                    - deleted
                    - is_new_webhook
                    - webhook_version
                    - org
                    description: Details of the current active project (null if accessing with org-level credentials)
                  api_key:
                    type: object
                    nullable: true
                    properties:
                      auto_id:
                        type: number
                        description: Internal auto-incrementing ID for the API key
                        example: 7890
                      id:
                        type: string
                        description: UUID identifier for the API key
                        example: 550e8400-e29b-41d4-a716-446655440003
                      name:
                        type: string
                        description: User-defined name for the API key
                        example: Development Key
                      project_id:
                        type: string
                        format: projectId
                        description: Short, URL-friendly unique identifier for the associated project
                        example: pr_1a2b3c4d5e6f
                      org_member_id:
                        type: string
                        description: UUID identifier for the organization member who owns this API key
                        example: 550e8400-e29b-41d4-a716-446655440002
                      created_at:
                        type: string
                        description: Date and time when the API key was created
                        example: '2023-05-01T10:00:00.000Z'
                      updated_at:
                        type: string
                        description: Date and time when the API key was last modified
                        example: '2023-05-01T10:00:00.000Z'
                      deleted_at:
                        type: string
                        nullable: true
                        description: Date and time when the API key was deleted (if applicable)
                      key:
                        type: string
                        description: The actual API key value (usually only shown once during creation)
                        example: ak_a1b2c3d4e5f6g7h8i9j0
                      deleted:
                        type: boolean
                        description: Flag indicating if the API key has been deleted
                        example: false
                    required:
                    - auto_id
                    - id
                    - name
                    - project_id
                    - org_member_id
                    - created_at
                    - updated_at
                    - deleted_at
                    - key
                    - deleted
                    description: Details of the API key used for authentication (null if using session auth)
                  org_member:
                    type: object
                    properties:
                      id:
                        type: string
                        description: UUID identifier for the organization member
                        example: 550e8400-e29b-41d4-a716-446655440002
                      email:
                        type: string
                        description: Email address of the authenticated user
                        example: user@example.com
                      name:
                        type: string
                        description: Display name of the authenticated user
                        example: John Doe
                      role:
                        type: string
                        description: Access role of the authenticated user within the organization
                        example: admin
                      metadata:
                        type: object
                        properties:
                          createdInBetterAuth:
                            type: boolean
                            description: Whether the user was created via Better Auth (dashboard signup).
                          prefers_old_dashboard:
                            type: boolean
                            description: If true, the user will be redirected to the legacy dashboard at platform.composio.dev.
                          onboarding_platform:
                            type: string
                            enum:
                            - consumer
                            - developer
                            description: Platform the user onboarded on.
                          seen_flow_consumer:
                            type: boolean
                            description: True once the user has completed the consumer onboarding flow.
                          seen_flow_developer:
                            type: boolean
                            description: True once the user has completed the developer onboarding flow.
                          seen_flow_cli:
                            type: boolean
                            description: True once the user has completed the CLI onboarding flow.
                          seen_connect_announcement:
                            type: boolean
                            description: True once the user has dismissed the Composio For You announcement modal in the developer dashboard.
                        additionalProperties:
                          anyOf:
                          - type: string
                          - type: boolean
                          - type: number
                        description: User metadata (JSONB). Typed keys are shown; additional keys pass through unchanged.
                    required:
                    - id
                    - email
                    - name
                    - role
                    - metadata
                    description: Information about the authenticated user
                    example:
                      id: 550e8400-e29b-41d4-a716-446655440002
                      email: user@example.com
                      name: John Doe
                      role: admin
                      metadata:
                        prefers_old_dashboard: false
                required:
                - project
                - api_key
                - org_member
                description: Response containing user session information
        '400':
          description: Bad request. The request format may be invalid or missing required parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. Authentication is required or the provided credentials are invalid or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden. The authenticated user does not have permission to access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found. The requested project, organization, or member resource could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error. An unexpected error occurred while processing the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v3/auth/session/logout:
    post:
      summary: End user session and clear authentication
      description: Terminates the current user session by invalidating authentication cookies and tokens. This effectively signs the user out of the application. After logout, the user will need to authenticate again to access protected resources.
      tags:
      - Authentication
      operationId: postAuthSessionLogout
      security:
      - CookieAuth: []
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      responses:
        '201':
          description: Logout operation completed successfully. The session has been terminated and authentication cookies have been invalidated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Human-readable result message of the logout operation
                    example: Logout successful
                required:
                - message
        '401':
          description: Unauthorized. The request requires valid authentication which was not provided.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Human-readable description of the error that occurred
                    example: Authentication required
                  code:
                    type: string
                    description: Optional machine-readable error code for programmatic handling
                    example: AUTH_REQUIRED
                required:
                - message
        '500':
          description: Internal server error. An unexpected error occurred while processing the logout request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Human-readable description of the error that occurred
                    example: Authentication required
                  code:
                    type: string
                    description: Optional machine-readable error code for programmatic handling
                    example: AUTH_REQUIRED
                required:
                - message
  /api/v3/connected_accounts/{nanoid}/refresh:
    post:
      summary: Refresh authentication for a connected account
      description: Initiates a new authentication flow for a connected account when credentials have expired or become invalid. This may generate a new authentication URL for OAuth flows or refresh tokens for other auth schemes.
      tags:
      - Authentication
      operationId: postConnectedAccountsByNanoidRefresh
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      parameters:
      - schema:
          type: string
          format: connectedAccountId
        required: true
        description: The unique identifier of the connected account
        example: ca_1a2b3c4d5e6f
        name: nanoid
        in: path
      - schema:
          type: string
          format: uri
        required: false
        name: redirect_url
        in: query
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                redirect_url:
                  type: string
                  format: uri
                validate_credentials:
                  type: boolean
                  default: false
                  description: '[EXPERIMENTAL] Whether to validate the provided credentials, validates only for API Key Auth scheme'
                  x-experimental: true
      responses:
        '200':
          description: Successfully refreshed the connected account authentication. For OAuth flows, a new redirect URL is provided.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The unique identifier of the connected account
                  status:
                    type: string
                    enum:
                    - INITIALIZING
                    - INITIATED
                    - ACTIVE
                    - FAILED
                    - EXPIRED
                    - INACTIVE
                    - REVOKED
                    description: The current status of the connected account (e.g., active, pending, failed)
                  redirect_url:
                    type: string
                    nullable: true
                    description: The URL to which the user should be redirected to complete the authentication process (null for auth schemes that do not require redirection)
                required:
                - id
                - status
                - redirect_url
                description: Response schema for a refreshed connected account authentication
                example:
                  id: ca_1a2b3c4d5e6f
                  status: ACTIVE
                  redirect_url: https://app.example.com/oauth/callback
        '400':
          description: Bad request - Invalid nanoid format or the account cannot be refreshed in its current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Insufficient permissions to refresh this connected account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found - Connected account does not exist or was deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict - The connection cannot be refreshed because of a permanent attribute (e.g. its auth scheme does not support refresh, such as API_KEY or BEARER_TOKEN)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable entity - The connection is in an invalid state for refresh (e.g. connection-data validation failed, or the stored connection status is incompatible with reinitiation)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error - Failed to refresh the connected account authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: number
            slug:
              type: string
            status:
              type: number
            request_id:
              type: string
            suggested_fix:
              type: string
            errors:
              type: array
              items:
                type: string
          required:
          - message
          - code
          - slug
          - status
      required:
      - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Project API key authentication
    UserApiKeyAuth:
      type: apiKey
      in: header
      name: x-user-api-key
      description: User API key authentication
    CookieAuth:
      type: apiKey
      in: cookie
      name: authToken
      description: Cookie-based session authentication
    OrgApiKeyAuth:
      type: apiKey
      in: header
      name: x-org-api-key
      description: Organization API key authentication