medium Tokens API

openapi: 3.2.0
info:
  title: Medium OAuth2 Tokens API
  description: The Medium OAuth2 API enables third-party applications to authenticate and authorize users to act on their behalf on the Medium platform.
  version: '1.0'
  contact:
    name: Medium Support
    url: https://help.medium.com
  termsOfService: https://policy.medium.com/medium-terms-of-service-9db0094a1e0f
servers:
- url: https://medium.com/m/oauth
  description: OAuth2 Authorization Server
- url: https://api.medium.com/v1
  description: Token Exchange Endpoint
tags:
- name: Tokens
  description: Endpoints for exchanging authorization codes for access tokens and refreshing expired access tokens.
paths:
  /tokens:
    post:
      operationId: exchangeAuthorizationCode
      summary: Exchange authorization code for tokens
      description: Exchanges an authorization code obtained from the authorization callback for an access token and a refresh token. The access token is valid for 60 days and is used to authenticate API requests on behalf of the user. The refresh token can be used to obtain a new access token when the current one expires.
      tags:
      - Tokens
      servers:
      - url: https://api.medium.com/v1
        description: Token Exchange Endpoint
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - code
              - client_id
              - client_secret
              - grant_type
              - redirect_uri
              properties:
                code:
                  type: string
                  description: The authorization code received from the authorization callback redirect.
                client_id:
                  type: string
                  description: The client ID of the application.
                client_secret:
                  type: string
                  description: The client secret of the application.
                grant_type:
                  type: string
                  enum:
                  - authorization_code
                  description: Must be set to "authorization_code" for the initial token exchange.
                redirect_uri:
                  type: string
                  format: uri
                  description: The same redirect URI used during the authorization request.
      responses:
        '200':
          description: Successfully exchanged the authorization code for tokens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          description: The authorization code is invalid, expired, or the client credentials are incorrect.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /tokens/refresh:
    post:
      operationId: refreshAccessToken
      summary: Refresh an access token
      description: Exchanges a refresh token for a new access token. This endpoint is used when the current access token has expired. The new access token is valid for another 60 days. A new refresh token may also be returned.
      tags:
      - Tokens
      servers:
      - url: https://api.medium.com/v1
        description: Token Exchange Endpoint
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - refresh_token
              - client_id
              - client_secret
              - grant_type
              properties:
                refresh_token:
                  type: string
                  description: The refresh token obtained from a previous token exchange.
                client_id:
                  type: string
                  description: The client ID of the application.
                client_secret:
                  type: string
                  description: The client secret of the application.
                grant_type:
                  type: string
                  enum:
                  - refresh_token
                  description: Must be set to "refresh_token" for token refresh requests.
      responses:
        '200':
          description: Successfully refreshed the access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          description: The refresh token is invalid, expired, or the client credentials are incorrect.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    TokenResponse:
      type: object
      description: The response from a successful token exchange or refresh containing the access token, refresh token, and metadata.
      properties:
        token_type:
          type: string
          enum:
          - Bearer
          description: The type of token issued. Always "Bearer".
        access_token:
          type: string
          description: The access token used to authenticate API requests on behalf of the user. Valid for 60 days.
        refresh_token:
          type: string
          description: The refresh token used to obtain a new access token when the current one expires.
        scope:
          type: array
          items:
            type: string
            enum:
            - basicProfile
            - listPublications
            - publishPost
            - uploadImage
          description: The list of scopes granted by the user during authorization.
        expires_at:
          type: integer
          format: int64
          description: The timestamp in milliseconds at which the access token expires.
    Error:
      type: object
      description: An error response from the Medium OAuth2 API containing error details.
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                description: A human-readable description of the error.
              code:
                type: integer
                description: The numeric error code identifying the error type.
externalDocs:
  description: Medium API Authentication Documentation
  url: https://github.com/Medium/medium-api-docs#2-authentication