Vanilla Forums Tokens API

openapi: 3.0.3
info:
  description: API access to your community.
  title: Vanilla Addons Tokens API
  version: '2.0'
servers:
- url: https://open.vanillaforums.com/api/v2
tags:
- name: Tokens
paths:
  /tokens:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Token'
                type: array
          description: Success
      tags:
      - Tokens
      summary: Get a list of access token IDs for the current user.
      x-addon: dashboard
      parameters:
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
    post:
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
          description: Success
      tags:
      - Tokens
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Token'
        required: true
      summary: Issue a new access token for the current user.
      x-addon: dashboard
  /tokens/oauth:
    post:
      summary: Exchange an OAuth access token for a Vanilla access token.
      description: 'This endpoint takes an access token from your OAuth 2 provider and exchanges it for a Vanilla access token. If no matching user exists in Vanilla, one will be created and an access token will be issued for them.


        In order to use this endpoint, the access token calls out to the API defined in the OAuth connection so it must have a scope that has access to the user''s profile or else it will fail.


        The access tokens provided by this endpoint are relatively short lived, so make sure you take note of the `dateExpires` in the response and have a strategy for refreshing the access token for long lived client sessions.'
      tags:
      - Tokens
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                clientID:
                  type: string
                  description: Your OAuth client ID used to identify the specific OAuth connection.
                oauthAccessToken:
                  type: string
                  description: Your OAuth access token with scope to access the user's profile information.
              required:
              - clientID
              - oauthAccessToken
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessToken:
                    type: string
                    description: The access token for Vanilla.
                  dateExpires:
                    type: string
                    format: date-time
                    description: The date/time that the access token will expire.
                required:
                - accessToken
                - dateExpires
              example:
                accessToken: va.MtVMRtHgB5Hipdb3HI86VqrdBlI4qWMz.QCw5cA.WkNNEV_
                dateExpires: '2019-08-30T14:37:52Z'
        '400':
          description: The user profile was successfully fetched, but was malformed in some way.
        '403':
          description: 'Forbidden. The OAuth access token didn''t have permission to access the user information or failed in some other way.


            If you get this error then make sure that the profile endpoint on **your** site returns a profile the access tokens you are providing to this site.

            '
        '404':
          description: The provided client ID did not match the client ID that was configured within Vanilla.
        '500':
          description: OAuth is either not enabled or is not configured on Vanilla.
      x-addon: dashboard
  /tokens/roles:
    post:
      summary: Issue a JWT that includes the current user's roles as its claims
      description: 'This is primarily intended for internal use on client-side code to authenticate to specific API endpoints where the response generated depends on the set of roles and associated permissions, but does not depend on the identity of the requesting user.


        As many users may share a limited set of roles, this approach allows for caching responses to these endpoints for short periods, to improve overall page responsiveness while reducing server-side load.'
      tags:
      - Tokens
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  roleToken:
                    type: string
                    description: A signed JWT issued for the current user containing the set of roles assigned to this user in its claims.
                  expires:
                    type: string
                    format: date-time
                    description: The UTC date/time that the role token expires.
                required:
                - roleToken
                - expires
              example:
                roleToken: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
                expires: '2024-11-19T19:17:45'
        '403':
          description: 'Forbidden. Role tokens cannot be issued to unauthenticated users.

            '
      x-addon: dashboard
  /tokens/{id}:
    delete:
      parameters:
      - description: 'The numeric ID of a token.

          '
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Success
      tags:
      - Tokens
      summary: Revoke an access token.
      x-addon: dashboard
    get:
      parameters:
      - description: 'The numeric ID of a token.

          '
        in: path
        name: id
        required: true
        schema:
          type: integer
      - description: 'A valid CSRF token for the current user.

          '
        in: query
        name: transientKey
        required: true
        schema:
          minLength: 1
          type: string
      - name: fields
        in: query
        style: form
        description: Only return fields with these keys from the output. Use dot notation for nested fields.
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
          description: Success
      tags:
      - Tokens
      summary: Reveal a usable access token.
      x-addon: dashboard
components:
  schemas:
    Token:
      properties:
        accessToken:
          description: A signed version of the token.
          minLength: 1
          type: string
        accessTokenID:
          description: The unique numeric ID.
          type: integer
        dateInserted:
          description: When the token was generated.
          format: date-time
          type: string
        name:
          description: A user-specified label.
          minLength: 1
          nullable: true
          type: string
        dateLastUsed:
          description: Last time a token was used.
          format: date-time
          type: string
      required:
      - accessTokenID
      - name
      - accessToken
      - dateInserted
      type: object
      x-addon: dashboard
x-resourceEvents:
  emailTemplates:
    x-feature: Feature.emailTemplates.Enabled
    name: Email Template
    type: emailTemplate
  notification:
    x-addon: dashboard
    name: Notification
    type: notification
  reaction:
    name: Reaction
    type: reaction
  user:
    x-addon: dashboard
    name: User
    type: user
  comment:
    x-addon: vanilla
    name: Comment
    type: comment
  discussion:
    x-addon: vanilla
    name: Discussion
    type: discussion
  escalation:
    x-addon: vanilla
    name: Escalation
    type: cmdEscalation
  report:
    x-addon: vanilla
    name: Report
    type: report
  userNote:
    x-addon: warnings2
    name: User Note
    type: userNote
x-aliases:
  AssetOut:
    type:
      description: The type of the asset.
      type: string
    url:
      type: string
      description: Absolute URL of the asset.
    content-type:
      description: The content-type of the asset.
      type: string
      example: application/json
  StringAssetOut:
    type:
      description: The type of the asset.
      type: string
    url:
      type: string
      description: Absolute URL of the asset.
    content-type:
      description: The content-type of the asset.
      type: string
      example: application/json
    data:
      type: string
      description: Contents of the asset. May require an expand parameter to retreive.
    '200':
      content:
        application/json:
          schema:
            description: Contents of an asset.
            type: object
            properties:
              type:
                description: The type of the asset.
                type: string
                example: html
                enum:
                - html
                - css
                - js
              data:
                type: string
                example: <header>Hello Footer<footer />
                description: Contents of the asset. May require an expand parameter to retreive.
              content-type:
                description: The content-type of the asset.
                type: string
                example: text/html
              url:
                type: string
                description: Absolute URL of the resource.
                example: https://site.com/api/v2/themes/:themeID/assets/:assetName.ext?v=faasdf42d
      description: Success
  ThemeSlug:
    description: Unique theme slug.
    in: path
    name: themeID
    required: true
    schema:
      type: string
  AssetNotFound:
    description: JavaScript could not be found.
    content:
      application/json:
        schema:
          type: object
          properties:
            description:
              description: Verbose description of the error.
              nullable: true
              type: string
            message:
              description: Short description of the error.
              type: string
            status:
              description: Status code of the error response.
              type: integer
          required:
          - description
          - message
          - status
  ThemeIDParam:
    description: Unique themeID.
    in: path
    name: themeID
    required: true
    schema:
      type: integer
  StringAssetIn:
    description: An asset to be inserted.
    type: object
    properties:
      type:
        description: The type of the asset.
        type: string
        example: html
        enum:
        - html
        - css
        - js
      data:
        type: string
        example: <header>Hello Footer<footer />
        description: Contents of the asset. May require an expand parameter to retreive.
  JsonAssetIn:
    description: An asset to be inserted.
    type: object
    properties:
      type:
        type: string
        example: json
      data:
        type: object
        description: JSON content of the asset.
        example:
          global:
            mainColors:
              primary: '#5cc530'
  JsonAssetOut:
    '200':
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                type: string
                example: json
              data:
                type: object
                description: JSON content of the asset.
                example:
                  global:
                    mainColors:
                      primary: '#5cc530'
              content-type:
                description: The content-type of the asset.
                type: string
                example: application/json
              url:
                type: string
                description: Absolute URL of the resource.
                example: https://site.com/api/v2/themes/:themeID/assets/:assetName.ext?v=faasdf42d
      description: Success
  DeleteAsset:
    parameters:
    - description: Unique themeID.
      in: path
      name: themeID
      required: true
      schema:
        type: integer
    responses:
      '204':
        description: Success
    tags:
    - Theme Assets
    summary: Delete theme asset.
  StringPutAsset:
    parameters:
    - description: Unique themeID.
      in: path
      name: themeID
      required: true
      schema:
        type: integer
    requestBody:
      required: true
      content:
        application/json:
          schema:
            description: An asset to be inserted.
            type: object
            properties:
              type:
                description: The type of the asset.
                type: string
                example: html
                enum:
                - html
                - css
                - js
              data:
                type: string
                example: <header>Hello Footer<footer />
                description: Contents of the asset. May require an expand parameter to retreive.
    responses:
      '200':
        content:
          application/json:
            schema:
              description: Contents of an asset.
              type: object
              properties:
                type:
                  description: The type of the asset.
                  type: string
                  example: html
                  enum:
                  - html
                  - css
                  - js
                data:
                  type: string
                  example: <header>Hello Footer<footer />
                  description: Contents of the asset. May require an expand parameter to retreive.
                content-type:
                  description: The content-type of the asset.
                  type: string
                  example: text/html
                url:
                  type: string
                  description: Absolute URL of the resource.
                  example: https://site.com/api/v2/themes/:themeID/assets/:assetName.ext?v=faasdf42d
        description: Success
    tags:
    - Theme Assets
    summary: Set theme asset or replace if already exists.
  HtmlPutAssetContentType:
    parameters:
    - description: Unique themeID.
      in: path
      name: themeID
      required: true
      schema:
        type: integer
    requestBody:
      required: true
      content:
        text/html:
          schema:
            type: string
            description: HTML contents.
            example: <div>Hello HTML Asset!</div>
    responses:
      '200':
        content:
          text/html:
            schema:
              type: string
              description: HTML contents.
              example: <div>Hello HTML Asset!</div>
        description: Success
    tags:
    - Theme Assets
    summary: Set theme asset or replace if already exists.
  JsPutAssetContentType:
    parameters:
    - description: Unique themeID.
      in: path
      name: themeID
      required: true
      schema:
        type: integer
    requestBody:
      required: true
      content:
        application/javascript:
          schema:
            type: string
            description: HTML contents.
            example: console.log('Hello Javascript')
    responses:
      '200':
        content:
          application/javascript:
            schema:
              type: string
              description: HTML contents.
              example: console.log('Hello Javascript')
        description: Success
    tags:
    - Theme Assets
    summary: Set theme asset or replace if already exists.
  CssPutAssetContentType:
    parameters:
    - description: Unique themeID.
      in: path
      name: themeID
      required: true
      schema:
        type: integer
    requestBody:
      required: true
      content:
        text/css:
          schema:
            type: string
            description: HTML contents.
            example: ".class {\n   color: orange;\n}\n"
    responses:
      '200':
        content:
          text/css:
            schema:
              type: string
              description: HTML contents.
              example: ".class {\n   color: orange;\n}\n"
        description: Success
    tags:
    - Theme Assets
    summary: Set theme asset or replace if already exists.
  JsonPutAsset:
    parameters:
    - description: Unique themeID.
      in: path
      name: themeID
      required: true
      schema:
        type: integer
    requestBody:
      required: true
      content:
        application/json:
          schema:
            description: An asset to be inserted.
            type: object
            properties:
              type:
                type: string
                example: json
              data:
                type: object
                description: JSON content of the asset.
                example:
                  global:
                    mainColors:
                      primary: '#5cc530'
    responses:
      '200':
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  example: json
                data:
                  type: object
                  description: JSON content of the asset.
                  example:
                    global:
                      mainColors:
                        primary: '#5cc530'
                content-type:
                  description: The content-type of the asset.
                  type: string
                  example: application/json
                url:
                  type: string
                  description: Absolute URL of the resource.
                  example: https://site.com/api/v2/themes/:themeID/assets/:assetName.ext?v=faasdf42d
        description: Success
    tags:
    - Theme Assets
    summary: Set theme asset or replace if already exists.
  JsonPutAssetContentType:
    parameters:
    - description: Unique themeID.
      in: path
      name: themeID
      required: true
      schema:
        type: integer
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            description: JSON contents of the asset.
            example:
              hello:
                json:
                  asset: true
    responses:
      '200':
        content:
          application/json:
            schema:
              type: object
              description: JSON contents of the asset.
              example:
                hello:
                  json:
                    asset: true
        description: Success
    tags:
    - Theme Assets
    summary: Set theme asset or replace if already exists.