Basecamp Token API

openapi: 3.2.0
info:
  title: Basecamp OAuth Token API
  description: The Basecamp OAuth 2.0 API provides the authorization code flow for obtaining access tokens on behalf of Basecamp users. Developers register their applications at launchpad.37signals.com to receive a client ID and client secret, then redirect users through the authorization flow. Access tokens expire after two weeks and can be refreshed using refresh tokens without requiring the user to re-authorize. All Basecamp API requests must include a valid Bearer token obtained through this flow.
  version: '1.0'
  contact:
    name: Basecamp Developer Support
    url: https://github.com/basecamp/bc3-api/blob/master/sections/authentication.md
  termsOfService: https://basecamp.com/terms
servers:
- url: https://launchpad.37signals.com
  description: Basecamp Authorization Server
tags:
- name: Token
  description: Token exchange and refresh endpoints
paths:
  /authorization/token:
    post:
      operationId: exchangeCodeForToken
      summary: Exchange code for token
      description: Exchanges an authorization code for an access token and refresh token. The authorization code is single-use and expires shortly after being issued. The resulting access token expires after two weeks.
      tags:
      - Token
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Access token and refresh token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /authorization/token/refresh:
    post:
      operationId: refreshAccessToken
      summary: Refresh access token
      description: Uses a refresh token to obtain a new access token without requiring the user to re-authorize. Refresh tokens do not expire but are revoked if the user revokes access.
      tags:
      - Token
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RefreshTokenRequest'
      responses:
        '200':
          description: New access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Unauthorized — invalid or expired credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request — missing or invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
    RefreshTokenRequest:
      type: object
      required:
      - type
      - client_id
      - client_secret
      - refresh_token
      properties:
        type:
          type: string
          description: Must be set to "refresh"
          enum:
          - refresh
        client_id:
          type: string
          description: Your application's client ID
        client_secret:
          type: string
          description: Your application's client secret
        refresh_token:
          type: string
          description: The refresh token from a previous token exchange
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: Bearer token to use in API requests
        refresh_token:
          type: string
          description: Token used to obtain new access tokens after expiry
        expires_in:
          type: integer
          description: Access token lifetime in seconds (approximately two weeks)
        token_type:
          type: string
          description: Token type, always "Bearer"
          enum:
          - Bearer
    TokenRequest:
      type: object
      required:
      - type
      - client_id
      - client_secret
      - code
      - redirect_uri
      properties:
        type:
          type: string
          description: Must be set to "web_server"
          enum:
          - web_server
        client_id:
          type: string
          description: Your application's client ID
        client_secret:
          type: string
          description: Your application's client secret
        code:
          type: string
          description: The authorization code received from the authorization redirect
        redirect_uri:
          type: string
          format: uri
          description: The redirect URI used in the authorization request
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'OAuth 2.0 Bearer token obtained via the authorization code flow. Include as "Authorization: Bearer {token}" in all API requests.'
externalDocs:
  description: Basecamp Authentication Documentation
  url: https://github.com/basecamp/bc3-api/blob/master/sections/authentication.md