openapi: 3.0.3
info:
  title: Access Token API
  version: 0.2.0
  description: |
    Generate Access Tokens for 3rd party applications that need access to epilot APIs.
tags:
- name: Access Tokens
  description: Create Access Tokens for epilot APIs
- name: Public
  description: Well known endpoints to verify tokens generated by this API
security:
- EpilotAuth: []
- EpilotOrg: []
paths:
  /v1/access-tokens:
    post:
      operationId: createAccessToken
      summary: createAccessToken
      description: |
        **Access Token type: `API`** (default if not specified):

        Generates a new Access Token to use for calling epilot APIs.

        Takes optionally a list of Roles assigned to the Access Token. Defaults to current user's assignments

        See [Permissions API docs](https://docs.epilot.io/api/permissions)

        **Access Token type: `JOURNEY`**:

        Generates a Public Access Token related to a journey.
        The journey id should be specfied.
      tags:
      - Access Tokens
      requestBody:
        description: Metadata for the Access Token
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenParameters'
            examples:
              api:
                value:
                  name: API Access Token
                  token_type: api
                  assignments: []
              journey:
                value:
                  name: Journey Access Token
                  token_type: journey
                  journey_id: u29g7-97gajsaog-028t02jag-a9a72tk
              portal:
                value:
                  name: Installer /End Customer Portal Access Token
                  token_type: portal
                  portal_id: END_CUSTOMER_PORTAL
      responses:
        '201':
          description: The new generated Access Token
          content:
            application/json:
              schema:
                allOf:
                - properties:
                    token:
                      $ref: '#/components/schemas/AccessToken'
                - $ref: '#/components/schemas/AccessTokenItem'
    get:
      operationId: listAccessTokens
      summary: listAccessTokens
      description: Lists all Access Tokens for current user (by default excludes system generated tokens)
      parameters:
      - in: query
        name: token_type
        description: Filter by token types
        schema:
          type: array
          items:
            $ref: '#/components/schemas/AccessTokenType'
      tags:
      - Access Tokens
      responses:
        '200':
          description: List of Access Tokens
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AccessTokenItem'
  /v1/access-tokens/{id}:
    delete:
      operationId: revokeAccessToken
      summary: revokeAccessToken
      description: Revokes an Access Token so it can't be used anymore.
      parameters:
      - name: id
        in: path
        schema:
          $ref: '#/components/schemas/AccessTokenId'
        required: true
      tags:
      - Access Tokens
      responses:
        '200':
          description: The revoked generated Access Token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessTokenItem'
  /v1/access-tokens/.well-known/jwks.json:
    get:
      operationId: getAccessTokenJwks
      summary: getAccessTokenJwks
      description: Get jwks public key set to verify access tokens generated by this API
      tags:
      - Public
      security: []
      responses:
        '200':
          description: Set of jwks
          content:
            application/json:
              schema:
                type: object
                properties:
                  keys:
                    type: array
                    items:
                      type: object
                      properties:
                        alg:
                          type: string
                          example: RS256
                        e:
                          type: string
                          example: AQAB
                        kid:
                          type: string
                          example: tXWU5mPMbRPczpbQwi6vbhLF4GgF3wlMDSyqo7pfeiw=
                        kty:
                          type: string
                          example: RSA
                        'n':
                          type: string
                          example: >-
                            h_QDoCjZ8W_trtYXaP7_S22wf5r5Wd9XBLED78oT44bJjQXn8ddcFV8Hik65_4IYXVX_hTTU4zpxe3H8vx2j7-Zz3O59mYMp5S0MzODNEdf5Y_2o19eis0brmAJniixsNlQ9LlYkdrVamrgaxHu3ZpP_99zkfFybYeuYoQNzb3PyrT8xVnz_USs_nlFMHpGUxvvz7gfKPqxcLvgLJr4cwI9yzaSY9CD4qW181QVcnL_WzpQ8xx6AuhhHZQ1l_3GG4InTk8ahE7U2ZHVu8RrX6d01pMgc3piEcet9RgFLnhbTg3YIiKGoAbN42wJn_x3lgIAC42T9mbmTsHyUdS6nUQ
                        use:
                          type: string
                          example: sig
  /v1/access-tokens/.well-known/openid-configuration:
    get:
      operationId: getAccessTokenOIDC
      summary: getAccessTokenOIDC
      description: |
        OpenID Connect configuration for Access Token API as identity provider

        Note: This API is not a fully compliant OAuth2.0 / OIDC identity provider, but this endpoint is useful to
        automate the process of verifying JWT tokens.
      tags:
      - Public
      security: []
      responses:
        '200':
          description: OpenID Configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  issuer:
                    type: string
                    format: uri
                    example: https://access-token.sls.epilot.io/v1/access-tokens
                  jwks_uri:
                    type: string
                    format: uri
                    example: https://access-token.sls.epilot.io/v1/access-tokens/.well-known/jwks.json
  /v1/access-tokens/public/.well-known/jwks.json:
    get:
      operationId: getPublicTokenJwks
      summary: getPublicTokenJwks
      description: Get jwks public key set to verify public tokens generated by this API
      tags:
      - Public
      security: []
      responses:
        '200':
          description: Set of jwks
          content:
            application/json:
              schema:
                type: object
                properties:
                  keys:
                    type: array
                    items:
                      type: object
                      properties:
                        alg:
                          type: string
                          example: RS256
                        e:
                          type: string
                          example: AQAB
                        kid:
                          type: string
                          example: tXWU5mPMbRPczpbQwi6vbhLF4GgF3wlMDSyqo7pfeiw=
                        kty:
                          type: string
                          example: RSA
                        'n':
                          type: string
                          example: >-
                            h_QDoCjZ8W_trtYXaP7_S22wf5r5Wd9XBLED78oT44bJjQXn8ddcFV8Hik65_4IYXVX_hTTU4zpxe3H8vx2j7-Zz3O59mYMp5S0MzODNEdf5Y_2o19eis0brmAJniixsNlQ9LlYkdrVamrgaxHu3ZpP_99zkfFybYeuYoQNzb3PyrT8xVnz_USs_nlFMHpGUxvvz7gfKPqxcLvgLJr4cwI9yzaSY9CD4qW181QVcnL_WzpQ8xx6AuhhHZQ1l_3GG4InTk8ahE7U2ZHVu8RrX6d01pMgc3piEcet9RgFLnhbTg3YIiKGoAbN42wJn_x3lgIAC42T9mbmTsHyUdS6nUQ
                        use:
                          type: string
                          example: sig
  /v1/access-tokens/public/.well-known/openid-configuration:
    get:
      operationId: getPublicTokenOIDC
      summary: getPublicTokenOIDC
      description: |
        OpenID Connect configuration for Access Token API a a public identity provider

        Note: This API is not a fully compliant OAuth2.0 / OIDC identity provider, but this endpoint is useful to
        automate the process of verifying JWT tokens.
      tags:
      - Public
      security: []
      responses:
        '200':
          description: OpenID Configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  issuer:
                    type: string
                    format: uri
                    example: https://access-token.sls.epilot.io/v1/access-tokens
                  jwks_uri:
                    type: string
                    format: uri
                    example: https://access-token.sls.epilot.io/v1/access-tokens/.well-known/jwks.json
components:
  securitySchemes:
    EpilotAuth:
      type: http
      scheme: bearer
      description: Authorization header with epilot OAuth2 bearer token
      bearerFormat: JWT
    EpilotOrg:
      description: Overrides the target organization to allow shared tenantaccess
      name: x-epilot-org-id
      in: header
      type: apiKey
  schemas:
    AccessToken:
      type: string
      description: A JWT Access Token
      example: eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...
    AccessTokenId:
      type: string
      example: api_5ZugdRXasLfWBypHi93Fk
    AccessTokenName:
      type: string
      description: Human readable name for access token
      example: Postman Access Token
    AccessTokenType:
      type: string
      enum:
      - api
      - journey
      - portal
      description: Access token type
      example: api
    AccessTokenJourneyId:
      type: string
      description: Journey ID for access token type "journey"
    PortalId:
      type: string
      description: Portal ID for access token type "portal"
    TokenParameters:
      anyOf:
      - $ref: '#/components/schemas/AccessTokenParameters'
      - $ref: '#/components/schemas/JourneyTokenParameters'
      - $ref: '#/components/schemas/PortalTokenParameters'
    AccessTokenParameters:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/AccessTokenName'
        token_type:
          type: string
          enum:
          - api
        assignments:
          $ref: '#/components/schemas/Assignments'
      required:
      - name
    JourneyTokenParameters:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/AccessTokenName'
        token_type:
          type: string
          enum:
          - journey
        journey_id:
          $ref: '#/components/schemas/AccessTokenJourneyId'
      required:
      - name
      - journey_id
    PortalTokenParameters:
      type: object
      additionalProperties: false
      properties:
        name:
          $ref: '#/components/schemas/AccessTokenName'
        token_type:
          type: string
          enum:
          - portal
        portal_id:
          $ref: '#/components/schemas/PortalId'
      required:
      - name
      - portal_id
    AccessTokenItem:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/AccessTokenId'
        created_at:
          type: string
          format: date-time
        name:
          $ref: '#/components/schemas/AccessTokenName'
        token_type:
          $ref: '#/components/schemas/AccessTokenType'
        journey_id:
          $ref: '#/components/schemas/AccessTokenJourneyId'
        portal_id:
          $ref: '#/components/schemas/PortalId'
        assignments:
          $ref: '#/components/schemas/Assignments'
      required:
      - id
      - created_at
      - name
    RoleId:
      type: string
      example: 123:owner
      description: 'Format: <organization_id>:<slug>'
    Assignments:
      type: array
      description: List of role ids attached to an user
      items:
        $ref: '#/components/schemas/RoleId'
servers:
- url: https://access-token.sls.epilot.io

