openapi: 3.2.0
info:
  title: Outline O Auth Clients API
  description: '# Introduction


    The Outline API is structured in an RPC style.'
  version: 0.1.0
  contact:
    email: hello@getoutline.com
  license:
    name: BSD-3-Clause
    url: https://github.com/outline/openapi/blob/main/LICENSE
servers:
- url: https://app.getoutline.com/api
  description: Cloud hosted
- url: https://{domain}/api
  description: Self-hosted on your own server
  variables:
    domain:
      default: example.com
security:
- BearerAuth: []
- OAuth2:
  - read
  - write
tags:
- name: OAuth Clients
  description: '`OAuthClients` represent OAuth clients that can be used to authenticate

    users with third-party services.'
paths:
  /oauthClients.info:
    post:
      tags:
      - OAuth Clients
      summary: Retrieve an OAuth client
      description: To retrieve information about an OAuth client you must pass either an `id` or a `clientId`.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Unique identifier for the OAuth client.
                  format: uuid
                clientId:
                  type: string
                  description: Public identifier for the OAuth client.
                  example: 2bquf8avrpdv31par42a
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/OAuthClient'
                  policies:
                    type: array
                    items:
                      $ref: '#/components/schemas/Policy'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: oauthClientsInfo
  /oauthClients.list:
    post:
      tags:
      - OAuth Clients
      summary: List accessible OAuth clients
      description: List all OAuth clients that the authenticated user has access to. This includes both clients created by the user and published clients available to the workspace.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pagination'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OAuthClient'
                  policies:
                    type: array
                    items:
                      $ref: '#/components/schemas/Policy'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: oauthClientsList
  /oauthClients.create:
    post:
      tags:
      - OAuth Clients
      summary: Create an OAuth client
      description: Create a new OAuth client application that can be used to authenticate users and access the API on their behalf.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the OAuth client.
                  example: My App
                description:
                  type: string
                  description: A short description of this OAuth client.
                  example: Integrate Acme Inc's services into Outline.
                developerName:
                  type: string
                  description: The name of the developer who created this OAuth client.
                  example: Acme Inc
                developerUrl:
                  type: string
                  description: The URL of the developer who created this OAuth client.
                  example: https://example.com
                avatarUrl:
                  type: string
                  description: A URL pointing to an image representing the OAuth client.
                redirectUris:
                  type: array
                  items:
                    type: string
                  description: List of redirect URIs for the OAuth client.
                  example:
                  - https://example.com/callback
                published:
                  type: boolean
                  description: Whether the OAuth client is available to other workspaces.
                  example: true
              required:
              - name
              - redirectUris
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/OAuthClient'
                  policies:
                    type: array
                    items:
                      $ref: '#/components/schemas/Policy'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: oauthClientsCreate
  /oauthClients.update:
    post:
      tags:
      - OAuth Clients
      summary: Update an OAuth client
      description: Update an existing OAuth client's properties such as name, description, redirect URIs, or published status.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Unique identifier for the OAuth client.
                  format: uuid
                name:
                  type: string
                  description: Name of the OAuth client.
                  example: My App
                description:
                  type: string
                  description: A short description of this OAuth client.
                  example: Integrate Acme Inc's services into Outline.
                developerName:
                  type: string
                  description: The name of the developer who created this OAuth client.
                  example: Acme Inc
                developerUrl:
                  type: string
                  description: The URL of the developer who created this OAuth client.
                  example: https://example.com
                avatarUrl:
                  type: string
                  description: A URL pointing to an image representing the OAuth client.
                redirectUris:
                  type: array
                  items:
                    type: string
                  description: List of redirect URIs for the OAuth client.
                  example:
                  - https://example.com/callback
                published:
                  type: boolean
                  description: Whether the OAuth client is available to other workspaces.
                  example: true
              required:
              - id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/OAuthClient'
                  policies:
                    type: array
                    items:
                      $ref: '#/components/schemas/Policy'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: oauthClientsUpdate
  /oauthClients.rotate_secret:
    post:
      tags:
      - OAuth Clients
      summary: Rotate the secret for an OAuth client
      description: Generate a new client secret for an OAuth client. The old secret will be invalidated immediately, so ensure your application is updated to use the new secret.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Unique identifier for the OAuth client.
                  format: uuid
              required:
              - id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/OAuthClient'
                  policies:
                    type: array
                    items:
                      $ref: '#/components/schemas/Policy'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: oauthClientsRotateSecret
  /oauthClients.delete:
    post:
      tags:
      - OAuth Clients
      summary: Delete an OAuth client
      description: Permanently delete an OAuth client and revoke all associated access tokens. This action cannot be undone.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Unique identifier for the OAuth client.
                  format: uuid
              required:
              - id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: oauthClientsDelete
components:
  responses:
    RateLimited:
      description: The request was rate limited.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            type: object
            properties:
              ok:
                type: boolean
                example: false
              error:
                type: string
                example: rate_limit_exceeded
              status:
                type: number
                example: 429
    Unauthorized:
      description: The current API key is not authorized to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthenticated:
      description: The API key is missing or otherwise invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The specified resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    OAuthClient:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the object.
          readOnly: true
          format: uuid
        name:
          type: string
          description: The name of this OAuth client.
          example: Acme Inc
        description:
          type:
          - string
          - 'null'
          description: A short description of this OAuth client.
          example: Integrate Acme Inc's services into Outline.
        developerName:
          type:
          - string
          - 'null'
          description: The name of the developer who created this OAuth client.
          example: Acme Inc
        developerUrl:
          type:
          - string
          - 'null'
          description: The URL of the developer who created this OAuth client.
          example: https://example.com
        avatarUrl:
          type:
          - string
          - 'null'
          description: A URL pointing to an image representing the OAuth client.
        clientId:
          type: string
          description: The client ID for the OAuth client.
          readOnly: true
          example: 2bquf8avrpdv31par42a
        clientSecret:
          type: string
          description: The client secret for the OAuth client.
          readOnly: true
          example: ol_sk_rapdv31...
        clientType:
          type: string
          description: The type of the OAuth client.
          readOnly: true
          enum:
          - public
          - confidential
        redirectUris:
          type: array
          items:
            type: string
          description: The redirect URIs for the OAuth client.
          example:
          - https://example.com/callback
        published:
          type: boolean
          description: Whether the OAuth client is available to other workspaces.
          example: true
        lastActiveAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Date and time when this OAuth client was last used.
          readOnly: true
        createdAt:
          type: string
          format: date-time
          description: Date and time when this OAuth client was created
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          description: Date and time when this OAuth client was updated
          readOnly: true
    Error:
      type: object
      properties:
        ok:
          type: boolean
          example: false
        error:
          type: string
        message:
          type: string
        status:
          type: number
        data:
          type: object
    Ability:
      description: A single permission granted by a policy
      example: true
      oneOf:
      - type: array
        items:
          type: string
      - type: boolean
    Pagination:
      type: object
      properties:
        offset:
          type: number
          example: 0
        limit:
          type: number
          example: 25
    Policy:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the object this policy references.
          format: uuid
          readOnly: true
        abilities:
          type: object
          description: The abilities that are allowed by this policy, if an array is returned then the individual ID's in the array represent the memberships that grant the ability.
          additionalProperties:
            $ref: '#/components/schemas/Ability'
          example:
            read: true
            update: true
            delete: false
  headers:
    RateLimit-Remaining:
      schema:
        type: integer
      description: How many requests are left in the current duration.
    RateLimit-Reset:
      schema:
        type: string
      description: Timestamp in the future the duration will reset.
    RateLimit-Limit:
      schema:
        type: integer
      description: The maximum requests available in the current duration.
    Retry-After:
      schema:
        type: integer
      description: Seconds in the future to retry the request, if rate limited.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.getoutline.com/oauth/authorize
          tokenUrl: https://app.getoutline.com/oauth/token
          refreshUrl: https://app.getoutline.com/oauth/token
          scopes:
            read: Read access
            write: Write access